OpenAPIを使ってAPIドキュメントを初めて作るときに参考になった資料をまとめました。
最初に読む資料
Swagger ではない OpenAPI Specification 3.0 による API サーバー開発
OpenAPIとはなんぞや？すこし前に話題になったSwaggerとの違いは？どのように書いていけば良い？などをざっくり頭に入れられる資料です。
スキーマファースト開発のためのOpenAPI（Swagger）設計規約
ざっくり記法が分かる記事です。OpenAPIはyamlファイルでの記述が基本ですが、後述する Stoplight Stadio というGUIエディターを使うと、比較的楽に作成管理ができます。
エラーレスポンス
OpenAPIというよりAPIそのもののエラーレスポンスの設計思想についてです。
REST API Error Handling Best Practices
Best Practices for API Error Handling | Nordic APIs |
エディター
Stoplight Studio | OpenAPI Design, Planning & Modeling Tool
OpenAPIをGUIで編集できるエディターです。StoplightというAPIドキュメントやAPIモックサーバーをホスティングするサービスが提供しているツールです。このサービスを使わなくてもエディターは無料で使えます。
リファレンス
Stoplight Studioを使って作成・編集したあと、yamlを参照すれば記法は大体つかめます。
redoc/openapi.yaml at master · Redocly/redoc
Redocというドキュメント化ツールのyamlが非常に参考になります。
特に、Redocでのドキュメント化を考えている場合はビルド後のドキュメントを見比べながら読むと、どこがどうなるのかが分かりやすいです。
OneOf, AllOf, AnyOf
Stoplight Studio使ってて最もわからなかったのがoneOf, anyOf, allOfという３つのオプションです。Swaggerのリファレンスを読むのがわかりやすかったです。
公開
Redocly/redoc: 📘 OpenAPI/Swagger-generated API Reference Documentation
OpenAPIのyamlをドキュメント化して公開するには、RedocでHTML化して公開するのがおすすめです。
[Swagger] OpenAPI3.0で記述したAPI仕様書をHTMLとして出力する - Qiita
これを読めば作成したyamlをHTMLにする手順がざっくり分かると思います。
OpenAPIの作成からGitHubActionsでチームに共有するまでの話
OpenAPI作成からRedocでドキュメント化して公開まで簡単にまとめられています。この記事での公開はS3でホスティングされていますが、ホスティングができればどこでも大丈夫です。
Boilerplate
dforest/openapi-redoc-boilerplate
OpenAPI + RedocでAPIドキュメントを作成するためのボイラープレートを作りました。よかったら参考にしてください。
Discussion