Swaggerで記述する際に気をつけること - NTT Communications Engineers' Blog

Swaggerでドキュメントを記述していて詰まるところが幾つかあります。今回はその注意点を紹介します。

リクエストパラメータは配列、レスポンスはオブジェクト

最も戸惑うのがこの点です。リクエストパラメータは次のように定義します。

"parameters": [
    {
        "name": "serviceId",
        "type": "string",
        "in": "query",
        "description": "サービスID",
        "required": true
    },
    {
        "name": "accessToken",
        "type": "string",
        "in": "query",
        "description": "アクセストークン",
        "required": true
    }
],

各リクエストパラメータを配列で定義します。inはパラメータをセットする場所で、

query : クエリストリング
formData : フォーム
header : HTTPヘッダー
path : パス
body : ボディー

が利用できます。

対してレスポンスは次のようになります。

"responses": {
    "200": {
            "description": "HTTP経由でアクセスするファイル情報",
            "schema": {
                "type": "object",
                "properties": {
                    "result": {
                        "type": "number",
                        "description": "エラーがなければ0"
                    },
                    "fileData": {
                        "type": "string",
                        "description": "ファイルのデータ"
                    },
                    "size": {
                        "type": "number",
                        "description": "ファイルサイズ"
                    },
                    "version": {
                        "type": "string",
                        "description": "バージョン番号"
                    }
                }
            }
        }
    }

schemaというキー以下に定義していきます。typeはデータ型で、

object
array
number
string
integer
boolean
file

などが使えます。

レスポンスが配列の場合の書き方

レスポンスが配列の場合、itemsというプロパティにその内容を記述していきます。これは固定のキーなので注意が必要です。

responses: 
  200: 
    description: ""
    schema: 
      type: "object"
      properties: 
        artists: 
          type: "object"
          properties: 
            href: 
              type: "string"
              description: ""
            items: 
              type: "array"
              items: 
                type: "object"
                properties: 
                  external_urls: 
                    type: "object"
                    properties: 
                      spotify: 
                        type: "string"
                        description: ""

配列がオブジェクトを返す場合であってもschemaというキーは不要です。これは最初だけにしか使われないようです。オブジェクトの場合はpropertiesというキーに対してデータを定義していきます。

Definitionsの使い分け

リクエストやレスポンスの形をDefinitionsとして定義することができます。これは全部で3つ用意されています。

Schema Definitions
Parameters Definitions
Response Definitions

Schemaはリクエスト、レスポンスで共用できます。他はそれぞれリクエスト、レスポンスのみで利用できます。目的に合わせて定義する場所を変更できますが、多くのRESful APIの場合リクエストとレスポンスの形式を合わせるので、結果的にSchema Definitionsしか使わないというのが管理上も楽ではないかと思います。