DockerでSwagger UIを起動してAPI仕様書をブラウザに表示する手順

1.はじめに

DockerでSwagger UI使用する際、DockerのコンテナにVolumeなどの設定を適切に行わないと、任意のAPI仕様書を参照させることが出来なかったため、Swagger UIにてAPI仕様書を参照できるまでの手順を記載する。

2.前提条件

Dockerが使用できる状態であること。

3.Swagger UIのコンテナを取得する

3-1.DockerHubからコンテナを取り込む

下記のコマンドを実行して、swagger-UIのコンテナをDockerに取り込む。

$ docker pull swaggerapi/swagger-ui

3-2.Swagger UIのコンテナを起動する

下記のコマンドを実行してswagger-uiのコンテナを起動する。

$ docker run -d -p 80:8080 swaggerapi/swagger-ui

※ -dオプションはバックグランド実行のオプション。実行時にコンテナのIDを表示してくれる。

3-3.サンプルページにアクセスする

下記のURLにブラウザでアクセスして起動確認をする。

http://{仮想マシンのIPアドレス}/

4.任意のAPI仕様書を参照する

4-1.マウントするディレクトリについて

SwaggerUIでは、HTTPで取得したドキュメントを参照してAPI仕様書をレンダリングする。
HTTPリクエストで参照が可能な場所にAPI仕様書が設定されている必要がある。SwaggerUIのコンテナではNginxがHTTPサーバとしてコンテナ内で動作するため、Nginxのドキュメントルートに任意のAPI仕様書をマウントすることで、Swagger UIからAPI仕様書が参照できるようになる。

4-2.Nginxのドキュメントルートについて

Nginxでは下記のディレクトリにドキュメントルートが設定されている。

/usr/shere/nginx/html

4-3.ドキュメントルート上に任意のディレクトリをマウントしてコンテナを起動する

DockerのコンテナではVolumeを設定することで、ホストマシンの任意のディレクトリをコンテナ上のディレクトリにマウントすることが出来る。
これを活用し、Nginxのドキュメントルート上にディレクトリをマウントすることで、任意のディレクトリを参照出来るようにする。
VolumeはDocker run コマンドのオプションで指定が可能。

$ docker run -d -p 80:8080 -v {マウントしたいホストマシンのディレクトリ}:/usr/share/nginx/html/{マウント先の任意のディレクトリ(api}とか)} -e API_URL={マウント先の任意のディレクトリ}/{API仕様書のファイル} swaggerapi/swagger-ui

※ -eオプションで設定しているAPI-URLの環境変数は、Swagger UIの画面を開いたときに初期値として参照するURLです。

※ 同じポートで多重起動は出来ないため、起動中のコンテナがある場合は起動コマンドを実行する前にstopコマンドなどで停止する

docker stop {コンテナID}

4-4.Swagger UIで任意のAPI仕様書を表示する

下記のURLにブラウザでアクセスして設定した任意のAPI仕様書が参照できることを確認する。

http://{仮想マシンのIPアドレス}/

5.参考情報

5-1.Dockerのよく使うコマンド

• Docker コマンドリファレンス
  http://docs.docker.jp/engine/reference/commandline/

5-2.Swagger UIの

• SwaggerUIのインストール手順(公式ドキュメント)
  https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

5-3.Nginxのディレクトリについて

• nginxの所有者・グループ・パーミッション
  https://gakumon.tech/nginx/nginx_permission_main.html

5-4.OpenAPI(Swagger)について

• SwaggerでRESTful APIの管理を楽にする
  https://qiita.com/disc99/items/37228f5d687ad2969aa2
• 開発効率を上げる！Swaggerの記法まとめ
  https://tech.starttoday-tech.com/entry/swagger_yaml