Swaggerで記述する際に気をつけること

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しか使わないというのが管理上も楽ではないかと思います。

Definitionsは継承できない

意外と面倒なのが一定の形を定義しつつ、必要に応じてフィールドを追加したいという要望です。しかしDefinitionsを継承してフィールドを追加することはできません。逆説的になりますが、Swagger.jsonを書きやすい形で文書を定義すると綺麗なAPI設計につながるかも知れません。

Markdownが使える、使えない部分がある

これはSwaggerというよりもSwagger UIの問題なのですが、項目によってはMarkdown記法が使えたり使えなかったりします。詳しくはSwaggerでのapi開発よもやま話の34ページ目を参照してください。

Swaggerはきちんとした仕様に基づいて作られてきた訳ではありません。そのため、現在はOpenAPI Initiativeによって定義がまとめられようとしています。仕様が定まれば表示上のツール、エディタの動作についても統一感が生まれて使い勝手が良くなることでしょう。