基本的な書き方は「swaggerの基礎。swaggerの設定ファイルの書き方とか」を参照
この記事は上記の内容を前提に、補足程度の情報を記載。
追加があったら都度、追記するかもしれない。
サンプルを記載する
そのまんま。swagger-editorのプレビューやswagger-UIのAPI一覧でサンプルを見ることができる。
ぱぱっと内容を把握するのに便利。
「examples:」から諸々を記載。以下の例はSwagger-editorのサンプルにある、instagramのyamlから抜粋して加工してある。
paths:
/users/{user-id}:
parameters:
- $ref: '#/parameters/user-id'
get:
security:
- key: []
- oauth:
- basic
tags:
- Users
description: Get basic information about a user.
responses:
200:
description: The user object
schema:
type: object
properties:
data:
$ref: '#/definitions/User'
##ここから
examples:
application/json:
id: 123
username: "taro"
full_name: "yamada taro"
profile_picture: "XXXXX"
bio: "YYY"
website: "http://XXXX.YYY.ZZZ"
counts:
media: 456
follows: 100
followed_by: 200
##ここまで
API名を明示的に指定する
パス名とAPI名を変えたいときに使う。
パスにV2などのバージョンを記載するけど、API名は変えたくない場合に便利(そんなケースあるか・・?)
また、プラットフォームによってAPI名がぶれるのも防いでくれる。
「operationId:」からAPI名を記載する。以下の例だと、URLは/user/123/のような感じだが、APIは「mogeId(int userId)」みたいになる。
paths:
/users/{user-id}:
operationId: moge_id
parameters:
- $ref: '#/parameters/user-id'
get:
##以下、省略
enumを定義する
そのまんま。enumが使える。ただし、リクエストとして渡したい場合、タイプ(in:)はbodyかqueryでしか指定できないので注意が必要。responseでは縛りなし。
「enum:」から諸々を記載する。
とは言うものの、実際のApiのリクエストはStringになるという・・・。
parameters:
user-type:
name: user-type
in: query
type: string
enum:
- WOMAN
- MAN
##以下、省略
バリデーションをする
string系なら文字列の長さと正規表現によるパターンマッチ、数字系(int,long,float,double)なら大小の条件を指定できる
プラットフォームによって機能したりしなかったりするので過信は禁物。
必ず生成されたコードを確認したほうが良い
full_name:
type: string
pattern: "[a-z0-9]{8,64}"
minLength: 8
maxLength: 64
patternで正規表現によるパターンマッチ、min/maxLengthで最小、最大長
user-id:
name: id
in: query
type: integer
format: int32
minimum: 0
exclusiveMinimum: true
maximum: 100
exclusiveMaximum: false
multipleOf: 10
minimum/maximunで最小、最大値、exclusive系でminimumなどで指定した値を含むかどうか(trueで含まなくなる)。上記の例ならidの条件は「0 < id <= 100」となる。
multipleOfは倍数指定。上記の例なら、idは10の倍数でないとNGになる。