35
38

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

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

Last updated at Posted at 2016-11-25

基本的な書き方は「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になる。

35
38
0

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
  3. You can use dark theme
What you can do with signing up
35
38

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?