OpenAPI + Swagger + Redoc + GitLab Pages で API ドキュメントを管理する

APIドキュメントを簡単に作成・閲覧できるようにしたいと思い、OpenAPI で作成、Swagger および Redoc で表示、GitLab Pages で公開までを行いました。 <img alt="" border="0" width="320" data-original-height="300" data-original-width="300" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTzWlAvRST5UDCd5me23ka8UNN-oJvGExcxB-OQIT79PTEEA2cyZjfV1WSvGxvTec5c4IcZWUTAbJo3_XR-n7wvHW-xA9NP5Olc9qizf0huCjOoPh0i8Vxu18xjg86cj7Z6blgjq00uOikZkgYA4oN0zAfrz293EB3Dv3PAMpSIgrZNi30S5IxuTTK/s320/openapi.png" hidden /> ## 概要 - OpenAPI で yaml を作成 - GitLab CI/DC により自動で Swagger および Redoc でビルドし、GitLab Pages に公開 - ローカル環境用に Swagger および Redoc を Docker で動かす ## ディレクトリ構造 今回試しに作成したファイル一式は以下となります。 詳細は後述します。 ```shell $ tree -a . ├── .gitlab-ci.yml ├── README.md ├── docker-compose.yml ├── openapi │ └── openapi.yaml └── public └── index.html ``` ## OpenAPI の yaml を作成 Open API Specification (OAS) は REST API の仕様を記述するフォーマットです。 記述方法についてはググったらたくさん出てくるので割愛します。 例えば、以下のような yaml を作成します。 ```yaml openapi: 3.0.0 info: version: 1.0.0 title: OpenAPI Sample paths: /users: get: summary: Get Users responses: '200': description: OK ``` ## ローカル環境の作成 ひとまず GitLab は置いておき、まずはローカル環境で Swagger および Redoc が動くようにしてみます。 ３つのサービスを動かしたかったので、docker-compose 使いました。 作成した docker-compose.yml は以下です。 ```yml version: '3' services: # エディター swagger-editor: image: swaggerapi/swagger-editor ports: - "8081:8080" # ビューワー（Swagger-UI 版） swagger-ui: image: swaggerapi/swagger-ui volumes: - ./openapi:/usr/share/nginx/html/openapi environment: API_URL: ./openapi/openapi.yaml # Swagger UIの画面を開いたときに初期値として表示するファイル ports: - '8082:8080' # ビューワー（Redoc 版） redoc: image: redocly/redoc volumes: - ./openapi:/usr/share/nginx/html/openapi environment: SPEC_URL: ./openapi/openapi.yaml # Redocの画面を開いたときに初期値として表示するファイル PORT: 8080 # nginx port(default:80) ports: - '8083:8080' ``` 特に難しいところはないかと思います。 `docker-compose up` で動かしたあと、ブラウザでアクセスすればOKです。 http://localhost:8081 で Swagger Editor にアクセスして編集が行えます。 http://localhost:8082 で Swagger UI での表示を確認できます。 http://localhost:8083 で Redoc での表示を確認できます。 ただ、Swagger Editor は別にいらなかったかもしれません。 私の場合、結局 VSCode で yaml を編集し、ブラウザの表示を更新して確認、ってやってます。 閲覧に関しては Swagger より Redoc のほうが個人的に見やすいですね。 ## GitLab Pages で公開する ローカルでの環境は以上で整ったので、次は GitLab に push したら自動ビルドを行って GitLab Pages に公開するように設定します。 GitLab Pages や GitLab CI/CD については割愛します。 Swagger + GitLab Pages については以下のページが参考になりました。 - https://lab.astamuse.co.jp/entry/2019/11/13/114500 ただ、今回 swagger-ui-dist のバージョンを上げたので、`sed` コマンドで修正するファイルを `index.html` から `swagger-initializer.js` に変更する必要がありました。 これについては以下のページが参考になりました。 - https://qiita.com/hidao/items/d13e7dda3da02d37dd45 Redoc + GitLab Pages については以下のページが参考になりました。 - https://medium.com/hoursofoperation/auto-generate-swagger-docs-to-gitlab-pages-ca040230df3a 以上の２つを組み合わせ、最終的に作成した .gitlab-ci.yml は以下です。 Swagger と Redoc のそれぞれで閲覧できるようにディレクトリを分けてみました。 プロキシ環境下でなければプロキシ関係の設定は不要です。 ```yml image: node:18-alpine variables: # プロキシサーバー PROXY: 'http://example:8080' # ドキュメントのあるディレクトリ DOCS_FOLDER: "swagger" # ドキュメントファイル SPEC_TO_DISPLAY: "openapi.yaml" # デプロイ先 DEPLOY_SWAGGER: "public/swagger" DEPLOY_REDOC: "public/redoc" cache: paths: - ./node_modules pages: stage: deploy before_script: # プロキシ環境下での下準備 - npm -g config set proxy $PROXY - npm -g config set https-proxy $PROXY - npm -g config set registry http://registry.npmjs.org/ - npm config set strict-ssl false # Swagger UI - npm install swagger-ui-dist@4.11.1 # Redoc - npm install -g redoc-cli@0.13.14 script: - mkdir -p $DEPLOY_SWAGGER - mkdir -p $DEPLOY_REDOC # Swagger UI - cp -rp node_modules/swagger-ui-dist/* $DEPLOY_SWAGGER - cp -rp $DOCS_FOLDER/* $DEPLOY_SWAGGER - sed -i "s#https://petstore\.swagger\.io/v2/swagger\.json#$SPEC_TO_DISPLAY#g" $DEPLOY_SWAGGER/swagger-initializer.js # Redoc - redoc-cli build -o $DEPLOY_REDOC/index.html $DOCS_FOLDER/$SPEC_TO_DISPLAY artifacts: paths: - public only: - main ``` ちなみに、Swagger の yaml ファイルは GitLab 上で Swagger でプレビュー表示されるので、外部に公開する必要がなければこれで十分かもしれません。 - https://blog.kyanny.me/entry/2020/08/06/012807 ## 参考 URL - https://medium.com/hoursofoperation/auto-generate-swagger-docs-to-gitlab-pages-ca040230df3a - https://overworker.hatenablog.jp/entry/2020/08/10/172207 - https://qiita.com/WinterYukky/items/366ed76dd4763a9b01e0 - https://lab.astamuse.co.jp/entry/2019/11/13/114500 - https://blog.kyanny.me/entry/2020/08/06/012807