Swaggerを記述するときのポイント
Swagger (Open API)3.0 がリリースされてから初めて使う機会があったので、自分なりの記述のポイントと、記述例をまとめました。
ポイント
- リソースIDやリソースといった複数のAPIで使われるプロパティ・オブジェクトを
components/schemas
に定義する。 - リソースIDのようなリクエストには指定しないが、レスポンスには指定されるプロパティは
readOnly: true
で表現する。 - 個別取得APIでは返却されるが、一覧取得APIでは返却されないプロパティは、スキーマを分離して
allOf
を指定して共通のプロパティを定義する。 - ページングや検索などの複数のAPIで使われるパラメータを
components/parameters
に定義する。 - エラーレスポンスの形式が共通である場合は
components/responses
に定義し、エラーコードをdescription
に表形式でまとめる。
記述例
参考:エディタ
Swaggerを編集するときは、Swagger Viewer(Visual Studio Codeプラグイン)が、リアルタイムプレビューに対応していて、かつ動作も軽いため使いやすい。
Author And Source
この問題について(Swaggerを記述するときのポイント), 我々は、より多くの情報をここで見つけました https://qiita.com/unhurried/items/c403787e1bb849b86f18著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Content is automatically searched and collected through network algorithms . If there is a violation . Please contact us . We will adjust (correct author information ,or delete content ) as soon as possible .