OpenAPIでAPIドキュメントを初めて作るときに読む資料

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 Interactive Demo

特に、Redocでのドキュメント化を考えている場合はビルド後のドキュメントを見比べながら読むと、どこがどうなるのかが分かりやすいです。

OneOf, AllOf, AnyOf

oneOf, anyOf, allOf, not

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ドキュメントを作成するためのボイラープレートを作りました。よかったら参考にしてください。