Docker を使って Swagger の編集環境を構築する #Docker

API ドキュメントを作成するには Swagger が便利です。
RAML や API Blueprint もありますが、周辺ツールの充実度が Swagger を使う利点だと思います。
ざっくり３つのツールがあります。

Swagger UI : API ドキュメント表示。サンプルリクエストも発行できる。
Swagger Editor : API 定義ファイル編集。プレビューできる。
Swagger Codegen : 複数のプログラミング言語の実装を生成。クライアントとサーバーの両方ある。

UI と Editor はオンライン版で十分かもしれませんが、オフライン状態で集中的にドキュメントを書きたいこともあるかもしれません。
そんな時のために、UI と Editor の環境を Docker Compose を使って構築します。

localhost に対して、以下の３つのパスでアクセスできるようにします。

パス	内容
/	Swagger Editor
/swagger-ui	Swagger UI
/swagger.yml	API定義ファイル

流れ

Swagger UI の HTML が入ったアーカイブを取得する
Docker Compose の設定ファイルを書く
Nginx の設定ファイルを書く
起動して API 定義ファイルを編集する

ドキュメント関係のフォルダとして、 docs の中に全部入れる想定とします。

1. Swagger UI のアーカイブ取得

まず、アーカイブをダウンロードします。ZIP を展開すると、中に dist/ フォルダがあります。
これはそのままホスティング可能なビューアーになります。
index.html を開くとすぐに使えますが、CORS の都合で読み取れるファイルの制限があります。

$ curl -LO https://github.com/swagger-api/swagger-ui/archive/v2.2.5.zip
$ unzip swagger-ui-2.2.5.zip
$ cp -r swagger-ui-2.2.5/dist docs/swagger-ui
$ rm -fr swagger-ui-2.2.5*

2. Docker Compose の設定ファイル

以下のような設定ファイル (docker-compose.yml) を用意します。

docker-compose.yml

version: '2'
services:
  web:
    image: nginx:latest
    ports:
      - "8000:80"
    links:
      - swagger_editor:swagger_editor
    depends_on:
      - swagger_editor
    volumes:
      - ./docs/swagger-editor.conf:/etc/nginx/conf.d/default.conf:ro
      - ./docs/swagger.yml:/usr/share/nginx/html/swagger.yml:ro
      - ./docs/swagger-ui:/usr/share/nginx/html/swagger-ui:ro
  swagger_editor:
    image: swaggerapi/swagger-editor:latest

Swagger Editor は Docker イメージがありますので、 swaggerapi/swagger-editorを使います。
それにリンクするように Nginx のコンテナを立ち上げて、必要なファイルをマウントさせます。

ここでは 8000 番ポートでアクセスできるように設定しています。
環境に応じてポート番号は調整しましょう。

3. Nginx の設定ファイル

Nginx の設定ファイルを swagger-editor.conf として用意します。
パスは以下の３つとします。

パス	内容
/	Swagger Editor
/swagger-ui	Swagger UI
/swagger.yml	API定義ファイル

swagger-editor.conf

server {
    listen       80;
    server_name  localhost;

    location / {
        proxy_pass    http://swagger_editor:8080;
    }

    location /swagger.yml {
        root   /usr/share/nginx/html;
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type, Origin, Authorization, Accept";
        add_header Access-Control-Allow-Credentials true;
    }

    location /swagger-ui {
        root   /usr/share/nginx/html;
    }
}

内部的なことは Docker Compose の設定と合わせましょう。
ここでは、Swagger Editor のホスト名は、Docker のコンテナ名になります。

また、 YAML は CORS に対応させておくと、違う何かに使いたい時も便利でしょう。

4. 起動

docker-compose コマンドで起動します。
swagger.yml がないと起動できませんので、編集すべきものを配置してから実行します。

$ docker-compose up -d web

ホストマシンに開放したポート番号でアクセスすると、エディタが表示されるはずです。
メニューから URL を指定して localhost の API 定義ファイルを指定します。
ビューアーを表示する場合は手動で URL を変更します。
何かが変、あるいは何も表示されない場合は docker-compose の logs コマンドで確認しましょう。

なお、エディタから URL を指定して編集を開始しても元ファイル自体が編集されるわけではありません。
ダウンロードして元ファイルを上書きしてください。（ここがちょっと不便）