Swaggerを記述するときのポイント

Swagger (Open API）3.0 がリリースされてから初めて使う機会があったので、自分なりの記述のポイントと、記述例をまとめました。

ポイント

• リソースIDやリソースといった複数のAPIで使われるプロパティ・オブジェクトを components/schemas に定義する。
• リソースIDのようなリクエストには指定しないが、レスポンスには指定されるプロパティは readOnly: true で表現する。
• 個別取得APIでは返却されるが、一覧取得APIでは返却されないプロパティは、スキーマを分離して allOf を指定して共通のプロパティを定義する。
• ページングや検索などの複数のAPIで使われるパラメータを components/parameters に定義する。
• エラーレスポンスの形式が共通である場合は components/responses に定義し、エラーコードを description に表形式でまとめる。

記述例

Gist - Swagger 3.0 Example

参考：エディタ

Swaggerを編集するときは、Swagger Viewer（Visual Studio Codeプラグイン）が、リアルタイムプレビューに対応していて、かつ動作も軽いため使いやすい。