Swaggerをちょっとだけ使いやすくするyamlの書き方

基本的な書き方は「swaggerの基礎。swaggerの設定ファイルの書き方とか」を参照

この記事は上記の内容を前提に、補足程度の情報を記載。
追加があったら都度、追記するかもしれない。

サンプルを記載する

そのまんま。swagger-editorのプレビューやswagger-UIのAPI一覧でサンプルを見ることができる。
ぱぱっと内容を把握するのに便利。
「examples:」から諸々を記載。以下の例はSwagger-editorのサンプルにある、instagramのyamlから抜粋して加工してある。

instagram.yamlのusers/{user-id}より

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)」みたいになる。

instagram.yamlのusers/{user-id}より

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)なら大小の条件を指定できる
プラットフォームによって機能したりしなかったりするので過信は禁物。
必ず生成されたコードを確認したほうが良い

string系

      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になる。