概要
自分がAPI仕様を作成するときのやり方をまとめる。
使うもの
- Git, Github, Github Pages
- Stoplight Studio
- VSCode
手順
リポジトリ作成 & Swagger UIファイル取得
- OpenAPI Specificationの表示用にSwagger UIファイル取得
- https://github.com/swagger-api/swagger-ui のdistフォルダの中身が必要。
- Github Pagesでdocsフォルダを公開予定なのでそこに入れる。
$ git clone git@github.com:swagger-api/swagger-ui.git
$ mkdir docs
$ cp -r swagger-ui/dist/* docs
$ rm -r swagger-ui
ドキュメントを書く
- 効率化のため Stoplight Studio を利用
- 現状 Swagger UI が OpenAPI 3.1.0 に対応していないため3.0系利用
- 例: https://github.com/yoshikipom/todo_api/blob/main/docs/reference/todo-api.yaml
- エンドポイントが多い時はTag付け推奨
Swagger UIのデフォルトページを作成したAPIのものにする
- Swagger UIの
index.htmlを編集。 - 例: https://github.com/yoshikipom/todo_api/blob/main/docs/index.html#L42
ローカルで確認
mainブランチにマージするまでGithub Pagesに反映されないため、プルリク段階では別の手段での確認が必要。
VSCodeプラグインを利用。
-
Swagger Viewerプラグインを導入 - VSCodeエディタでStoplight Studioで作ったyamlを開き、
Show All Commandsで ``Swagger Preview` を実行 - 表示確認
プルリク
- プルリク -> レビュー -> マージ
- PR例: https://github.com/yoshikipom/todo_api/pull/1/files
Github Pagesに展開
- Githubリポジトリの設定で
/docsフォルダをGithub Pagesで公開 - 例: https://yoshikipom.github.io/todo_api/index.html