Swaggerの利用基盤をdockerで構築しGitHub Pagesで公開する

|
featured image

APIの設計とWeb上への公開までをシュッとできる基盤をdockerで構築したのでシェアします。

Swaggerについて

OpenAPIのフォーマットに準拠したAPI仕様を定義できるツールです。

OpenAPIに従って認証部分やリクエスト、レスポンス形式などを具体的に整理できるので、draw.ioなどの描画ツールでは気づかない部分や漏れを防げます。

Swaggerの実態は静的コンテンツなので、GitHub PagesやAWS S3などにポンと置いて公開できます。

取り急ぎSwaggerを試したい場合はdocker Hubにimageがあるので、下記コマンドでささっと利用可能です。

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

Swaggerの利用基盤構築

取り急ぎSwaggerを試すなら前項のdockerコマンドで事足りますが、最終的には仕様書を公開してチーム内で見れるようにしたいという気持ちがあります。

そこで、編集とGitHub Pagesへの公開までスムーズに進められるよう、Swaggerの利用基盤を用意しました。

ディレクトリ構造

.
├── docker-compose.yml
├── setup.sh
└── spec
    └── sample.yml

docker-compose.yml

swagger-editorとnginxのコンテナを起動します。

API仕様の編集はswagger-editorで行います。

nginxは公開用に使うswagger-uiの見た目を確認するために用意しました。

version: '3'

services:
  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: dev-swagger-editor
    ports:
      - 8090:8080
    volumes:
      - ./dist/specification.yml:/specification.yml
    environment:
      SWAGGER_FILE: /specification.yml
  nginx:
    image: nginx:alpine
    container_name: dev-swagger-ui
    ports:
      - 8091:80
    volumes:
      - ./dist:/usr/share/nginx/html

setup.sh

初期設定用の処理を記載しています。公開用のファイル一式を入手するため、swagger-uiのコンテナを手元に落とし、中身のファイルを抜き出してホスト側に置くということをやっています。

#!/bin/bash

PWD=`pwd`
DIRECTORY="${PWD}/dist"

function setup() {
  touch specification.yml
  docker container run -d --name tmp-swagger-ui -e SWAGGER_JSON=/specification.yml -v $(pwd)/specification.yml:/specification.yml swaggerapi/swagger-ui
  docker container cp tmp-swagger-ui:/usr/share/nginx/html ./dist
  docker container rm -f tmp-swagger-ui
  rm ./dist/specification.yml
  mv specification.yml ./dist/
}

if [ ! -d "$DIRECTORY" ]; then
    printf 'Start running a setup script.\n'
    setup
    printf 'Finished.\n'
else
    printf 'Setup is already done.\n'
fi

使い方

下記コマンドを実行します。

sh ./setup.sh
docker compose up -d

localhost:8090にアクセスすればswagger-editorが開くので、そこでAPIの仕様を定義します。

localhost:8091にアクセスすればswagger-uiが開くので、公開用の見た目を確認します。

GitHub Pagesへの公開方法

ファイル一式をそのまま公開したいリポジトリへ移動させ、GitHub Pagesの設定をすればOKです。

公開用のファイルはdist/配下にあるので、そのパスを直接指定するか、一つ上の階層（rootディレクトリ）を指定しすればいいと思います。

APIの規模によってはディレクトリを分けた利したいと思うので、その場合はdist/ディレクトリの名前変更すれば良いです。例えば下記のようにapiA, apiB, apiCに変更し、公開パスをrootディレクトリにすれば、URLの末尾を /apiA/, /apiB/ にしてアクセスすることでそれぞれの仕様書のページを開けます。

.
├── docker-compose.yml
├── setup.sh
├── apiA # 公開したいAPI仕様書A
├── apiB # 公開したいAPI仕様書B
├── apiC # 公開したいAPI仕様書C
└── spec
    └── sample.yml

まとめ

APIの設計をシュッとできる基盤を用意できました。ちょっと気になる点があるので気が向いたら修正します。

↓リポジトリ

https://github.com/hodanov/docker-template-swagger