LoginSignup
2

More than 3 years have passed since last update.

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

Posted at

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プラグイン)が、リアルタイムプレビューに対応していて、かつ動作も軽いため使いやすい。

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
2