OpenAPI は API の定義書の形式であり、その定義書を元にした様々なツールです。元々 Swagger と名乗っていてそれが定義書だった OpenAPI に取り込まれた感じです（今も並行しているかも？この辺り怪しいです。Swagger も OpenAPI も同じものを指しているぐらいのふんわり認識）。
API Documentation & Design Tools for Teams ｜ Swagger
Docker を使うことで OpenAPI の細かい周辺機器に触らず API の定義書である yaml にのみ注力して OpenAPI を使えます。
使うベースイメージは次の swaggerapi/swagger-ui です。これが API 定義書の yaml をいい感じの HTML 形式のファイルに変換してくれます。
swaggerapi/swagger-ui – Docker Hub
### Dockerfile ###
FROM swaggerapi/swagger-ui:v3.35.0
RUN mkdir /usr/share/swagger && cp -r /usr/share/nginx/html /usr/share/swagger
### docker-compose.yml ###
swagger:
build:
context: ./docker/swagger # ↑のDockerfileを置いてあるディレクトリが ./docker/swagger
volumes:
- ./docs/swagger/api.yaml:/usr/share/nginx/html/api.yaml # 手元の api.yaml をいじってそれをDokcer内に即反映させます
- ./public/docs:/tmp/dump/html # ↓のコマンドでHTML形式のドキュメント一式を出力します
environment:
API_URL: api.yaml
ports:
- 8010:8080 # docker-machine の使っているIPの8010番ポートにアクセスするとドキュメントをブラウザで見れます
### shell ###
docker-compose exec swagger_member cp -r /usr/share/nginx/html /tmp/dump
# /tmp/dump にマウントしている ./public/docs 以下に HTML ドキュメントがコピー（出力）されます
# Docker を置けないステージング環境、共有テスト環境でもこの HTML ドキュメント一式を置けば OpenAPI の恩恵に預かれます
こんな感じで簡易な Dockerfile、コンテナ定義、ドキュメントで次の様なwebページに API 定義書を変換できます。
API 定義書の書き方はバージョンによって割と違います。記事を書いている時点では 3 系が最新の記法です。
記述の助けになるものは色々ありますが次の三つが特におすすめです。
OpenAPI Specification – Version 3.0.3 ｜ Swagger
まずは OpenAPI の仕様書です。どうにも分からなくなったらこれがバイブルです。これと OpenAPI の挙動が違っていたらバグなので GitHub の issue の出番です。
仕様書そのものは大変読みにくいです。手っ取り早く書くためのチートシートが欲しくなります。次のチートシートは日本語の逆引き的なチートシートであり、とっかかりに便利です。
OpenAPI Specification 3.0 チートシート – 朝日ネット 技術者ブログ
何の補助もないテキストエディタで OpenAPI に完全に従った yaml を書くのは難しいです。PhpStorm ならばその辺りのサポートもしてくれます。上がヘルプで下が OpenAPI 用のプラグインです。
OpenAPI — IntelliJ IDEA
OpenAPI Specifications – IntelliJ IDEs ｜ JetBrains
これを使うと次図の様にドキュメントを書きながらリアルタイムにプレビューを見れる他バリデーションもしてくれます。
