2
Help us understand the problem. What are the problem?

More than 3 years have passed since last update.

posted at

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

Register as a new user and use Qiita more conveniently

  1. You can follow users and tags
  2. you can stock useful information
  3. You can make editorial suggestions for articles
What you can do with signing up
2
Help us understand the problem. What are the problem?