OpenAPI 仕様

(以前はSwagger RESTful API Documentation Specification)

バージョン 2.0

このドキュメント内のキーワード「MUST」「MUST NOT」「REQUIRED」「SHALL」「SHALL NOT」「SHOULD」「SHOULD NOT」「RECOMMENDED」「MAY」「OPTIONAL」は、RFC 2119に記載されているように解釈されます。

Swagger仕様は、Apache License, Version 2.0の下でライセンスされています。

はじめに

Swagger™は、RESTful APIを記述および文書化するために使用されるプロジェクトです。

Swagger仕様は、このようなAPIを記述するために必要な一連のファイルを定義します。これらのファイルは、Swagger-UIプロジェクトによってAPIを表示するため、およびSwagger-Codegenによってさまざまな言語でクライアントを生成するために使用できます。テストツールなどの追加のユーティリティも、結果のファイルを活用できます。

改訂履歴

バージョン 日付 備考
2.0 2014-09-08 Swagger 2.0のリリース
1.2 2014-03-14 正式なドキュメントの初版。
1.1 2012-08-22 Swagger 1.1のリリース
1.0 2011-08-10 Swagger仕様の初版

定義

パスのテンプレート化

パスのテンプレート化とは、中括弧（{}）を使用してURLパスのセクションをパスパラメータで置き換え可能としてマークすることを指します。

MIMEタイプ

MIMEタイプの定義は、いくつかのリソースにわたって分散しています。MIMEタイプの定義は、RFC 6838に準拠している必要があります。

MIMEタイプの定義の例

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch
HTTPステータスコード

HTTPステータスコードは、実行された操作のステータスを示すために使用されます。利用可能なステータスコードは、RFC 7231およびIANA Status Code Registryに記載されています。

仕様

フォーマット

Swagger仕様に従ってRESTful APIを記述するファイルは、JSONオブジェクトとして表現され、JSON標準に準拠しています。JSONのスーパーセットであるYAMLも、Swagger仕様ファイルを表すために使用できます。

たとえば、フィールドが配列値を持つと言われる場合、JSON配列表現が使用されます

{
   "field" : [...]
}

APIはJSONを使用して記述されていますが、API自体にJSON入出力を強制するものではありません。

仕様内のすべてのフィールド名は**大文字と小文字を区別します**。

スキーマは2種類のフィールドを公開します。宣言された名前を持つ固定フィールドと、フィールド名に正規表現パターンを宣言するパターンフィールドです。パターンフィールドは、それぞれが固有の名前を持つ限り、複数回出現できます。

ファイル構造

APIのSwagger表現は単一のファイルで構成されます。ただし、定義の一部は、ユーザーの判断で個別のファイルに分割できます。これは、JSON Schema定義に従って、仕様の$refフィールドに適用されます。

慣例により、Swagger仕様ファイルはswagger.jsonという名前で付けられます。

データ型

Swagger Specificationのプリミティブデータ型は、JSON-Schema Draft 4でサポートされている型に基づいています。モデルは、JSON Schema Draft 4のサブセットであるスキーマオブジェクトを使用して記述されます。

追加のプリミティブデータ型"file"は、パラメーターオブジェクトとレスポンスオブジェクトによって、パラメーター型またはレスポンスをファイルとして設定するために使用されます。

プリミティブには、オプションの修飾子プロパティformatがあります。Swaggerは、使用されているデータ型をより詳細に定義するために、いくつかの既知のフォーマットを使用します。ただし、formatプロパティはオープンなstring値のプロパティであり、ドキュメントのニーズをサポートするために任意の値を設定できます。「email」や「uuid」などのフォーマットは、この仕様で定義されていなくても使用できます。formatプロパティが付随しない型は、JSON Schemaの定義に従います（上記で定義されているfile型を除く）。Swagger Specificationで定義されているフォーマットは次のとおりです。

一般的な名前 タイプ フォーマット コメント
整数 整数 int32 符号付き32ビット
長整数 整数 int64 符号付き64ビット
浮動小数点数 数値 浮動小数点数
倍精度浮動小数点数 数値 倍精度浮動小数点数
文字列 文字列
バイト 文字列 バイト base64エンコード文字
バイナリ 文字列 バイナリ 任意のオクテットシーケンス
ブール値 ブール値
日付 文字列 日付 full-date - RFC3339で定義されている通り
日時 文字列 日付と時刻 date-time - RFC3339で定義されている通り
パスワード 文字列 パスワード UIに入力を隠す必要があることを示唆するために使用されます。

スキーマ

Swaggerオブジェクト

これは、API仕様のルートドキュメントオブジェクトです。以前はResource ListingとAPI Declaration（バージョン1.2以前）であったものを1つのドキュメントに結合します。

固定フィールド
フィールド名 タイプ 説明
swagger 文字列 必須。 使用されているSwagger Specificationのバージョンを指定します。Swagger UIや他のクライアントがAPIリストを解釈するために使用できます。値は"2.0"である必要があります。
情報 情報オブジェクト 必須。 APIに関するメタデータを提供します。クライアントは必要に応じてこのメタデータを使用できます。
ホスト 文字列 APIを提供するホスト（名前またはIPアドレス）。これはホストのみであり、スキームやサブパスを含めるべきではありません。ポートを含めることはできます。hostが含まれていない場合、ドキュメントを提供するホスト（ポートを含む）が使用されます。hostはパスのテンプレート化をサポートしていません。
ベースパス 文字列 APIが提供されるベースパスで、hostに対する相対パスです。含まれていない場合、APIはhost直下で提供されます。値は先頭のスラッシュ（/）で始まる必要があります。basePathはパスのテンプレート化をサポートしていません。
スキーム [文字列] APIの転送プロトコル。値は、"http"、"https"、"ws"、"wss"のリストから選択する必要があります。schemesが含まれていない場合、Swagger定義自体にアクセスするために使用されたスキームがデフォルトとして使用されます。
消費する [文字列] APIが消費できるMIMEタイプのリスト。これはすべてのAPIにグローバルですが、特定のAPI呼び出しで上書きできます。値はMIMEタイプに記載されているとおりである必要があります。
生成する [文字列] APIが生成できるMIMEタイプのリスト。これはすべてのAPIにグローバルですが、特定のAPI呼び出しで上書きできます。値はMIMEタイプに記載されているとおりである必要があります。
パス パスオブジェクト 必須。 APIで利用可能なパスと操作。
定義 定義オブジェクト 操作によって生成および消費されるデータ型を保持するオブジェクト。
パラメーター パラメーター定義オブジェクト 操作全体で使用できるパラメーターを保持するオブジェクト。このプロパティは、すべての操作に対するグローバルパラメーターを**定義しません**。
レスポンス レスポンス定義オブジェクト 操作全体で使用できるレスポンスを保持するオブジェクト。このプロパティは、すべての操作に対するグローバルレスポンスを**定義しません**。
セキュリティ定義 セキュリティ定義オブジェクト 仕様全体で使用できるセキュリティスキーム定義。
セキュリティ [セキュリティ要件オブジェクト] API全体に適用されるセキュリティスキームの宣言。値のリストは、使用可能な代替セキュリティスキームを記述します（つまり、セキュリティ要件間に論理ORがあります）。個々の操作は、この定義をオーバーライドできます。
タグ [タグオブジェクト] 追加のメタデータを持つ仕様で使用されるタグのリスト。タグの順序は、解析ツールによる順序を反映するために使用できます。 操作オブジェクトによって使用されるすべてのタグが宣言されている必要はありません。宣言されていないタグは、ランダムに、またはツールのロジックに基づいて整理される場合があります。リスト内の各タグ名は一意である必要があります。
外部ドキュメント 外部ドキュメンテーションオブジェクト 追加の外部ドキュメント。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。

情報オブジェクト

このオブジェクトは、APIに関するメタデータを提供します。クライアントは必要に応じてこのメタデータを使用でき、便宜上Swagger-UIに表示することもできます。

固定フィールド
フィールド名 タイプ 説明
タイトル 文字列 必須。 アプリケーションのタイトル。
説明 文字列 アプリケーションの簡単な説明。GFM構文を使用してリッチテキスト表現にすることができます。
利用規約 文字列 APIの利用規約。
連絡先 連絡先オブジェクト 公開されたAPIの連絡先情報。
ライセンス ライセンスオブジェクト 公開されたAPIのライセンス情報。
バージョン 文字列 必須 アプリケーションAPIのバージョンを提供します（仕様のバージョンと混同しないでください）。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
情報オブジェクトの例
{
  "title": "Swagger Sample App",
  "description": "This is a sample server Petstore server.",
  "termsOfService": "https://swagger.dokyumento.jp/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.swagger.io/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://apache.dokyumento.jp/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: https://swagger.dokyumento.jp/terms/
contact:
  name: API Support
  url: http://www.swagger.io/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://apache.dokyumento.jp/licenses/LICENSE-2.0.html
version: 1.0.1

連絡先オブジェクト

公開されたAPIの連絡先情報。

固定フィールド
フィールド名 タイプ 説明
名前 文字列 連絡担当者/組織の識別名。
URL 文字列 連絡先情報を示すURL。URL形式である必要があります。
Eメール 文字列 連絡担当者/組織のメールアドレス。メールアドレスの形式である必要があります。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
連絡先オブジェクトの例
{
  "name": "API Support",
  "url": "http://www.swagger.io/support",
  "email": "[email protected]"
}

name: API Support
url: http://www.swagger.io/support
email: [email protected]

ライセンスオブジェクト

公開されたAPIのライセンス情報。

固定フィールド
フィールド名 タイプ 説明
名前 文字列 必須。 APIに使用されるライセンス名。
URL 文字列 APIに使用されるライセンスへのURL。URLの形式である必要があります。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
ライセンスオブジェクトの例
{
  "name": "Apache 2.0",
  "url": "https://apache.dokyumento.jp/licenses/LICENSE-2.0.html"
}

name: Apache 2.0
url: https://apache.dokyumento.jp/licenses/LICENSE-2.0.html

パスオブジェクト

個々のエンドポイントへの相対パスを保持します。パスはbasePathに追加されて完全なURLが構築されます。ACL制約のため、パスが空になる場合があります。

パターン化されたフィールド
フィールドパターン タイプ 説明
/{パス} パス項目オブジェクト 個々のエンドポイントへの相対パス。フィールド名はスラッシュで始まる必要があります。パスはbasePathに追加されて完全なURLが構築されます。パスのテンプレート化が許可されています。
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
パスオブジェクトの例
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "produces": [
        "application/json"
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/pet"
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    produces:
    - application/json
    responses:
      '200':
        description: A list of pets.
        schema:
          type: array
          items:
            $ref: '#/definitions/pet'

パス項目オブジェクト

単一のパスで利用可能な操作を記述します。ACL制約により、パスアイテムは空になる場合があります。パス自体はドキュメントビューアに公開されますが、利用可能な操作とパラメータは表示されません。

固定フィールド
フィールド名 タイプ 説明
$ref 文字列 このパスアイテムの外部定義を許可します。参照される構造は、パスアイテムオブジェクトの形式である必要があります。参照される定義とこのパスアイテムの定義の間に競合がある場合、動作は**未定義**です。
get オペレーションオブジェクト このパス上のGET操作の定義。
置く オペレーションオブジェクト このパス上のPUT操作の定義。
投稿 オペレーションオブジェクト このパス上のPOST操作の定義。
削除 オペレーションオブジェクト このパス上のDELETE操作の定義。
オプション オペレーションオブジェクト このパス上のOPTIONS操作の定義。
頭 オペレーションオブジェクト このパス上のHEAD操作の定義。
パッチ オペレーションオブジェクト このパス上のPATCH操作の定義。
パラメーター [パラメータオブジェクト | 参照オブジェクト] このパスの下で記述されたすべての操作に適用可能なパラメータのリスト。これらのパラメータは操作レベルで上書きできますが、そこで削除することはできません。リストには重複するパラメータを含めることはできません。一意のパラメータは、名前と場所の組み合わせで定義されます。リストは、Swaggerオブジェクトのパラメータで定義されているパラメータにリンクするために参照オブジェクトを使用できます。最大で1つの「body」パラメータが存在できます。
パターン化されたフィールド
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
パス項目オブジェクトの例
{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "produces": [
      "application/json",
      "text/html"
    ],
    "responses": {
      "200": {
        "description": "pet response",
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Pet"
          }
        }
      },
      "default": {
        "description": "error payload",
        "schema": {
          "$ref": "#/definitions/ErrorModel"
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "type": "array",
      "items": {
        "type": "string"
      },
      "collectionFormat": "csv"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  produces:
  - application/json
  - text/html
  responses:
    '200':
      description: pet response
      schema:
        type: array
        items:
          $ref: '#/definitions/Pet'
    default:
      description: error payload
      schema:
        $ref: '#/definitions/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  type: array
  items:
    type: string
  collectionFormat: csv

オペレーションオブジェクト

パス上の単一のAPI操作を記述します。

固定フィールド
フィールド名 タイプ 説明
タグ [文字列] APIドキュメント制御用のタグのリスト。タグは、リソースまたはその他の修飾子による操作の論理グループ化に使用できます。
概要 文字列 操作が何をするかの簡単な要約。swagger-uiでの最大可読性を実現するには、このフィールドは120文字未満である必要があります。
説明 文字列 操作動作の詳細な説明。GFM構文を使用してリッチテキスト表現にすることができます。
外部ドキュメント 外部ドキュメンテーションオブジェクト この操作に関する追加の外部ドキュメント。
operationId 文字列 操作を識別するために使用される一意の文字列。IDは、APIで記述されているすべての操作の中で一意である必要があります。ツールやライブラリはoperationIdを使用して操作を一意に識別する可能性があるため、一般的なプログラミングの命名規則に従うことをお勧めします。
消費する [文字列] 操作が消費できるMIMEタイプのリスト。これは、Swaggerオブジェクトのconsumes定義を上書きします。グローバル定義をクリアするために空の値を使用することもできます。値はMIMEタイプに記載されているとおりである必要があります。
生成する [文字列] 操作が生成できるMIMEタイプのリスト。これは、Swaggerオブジェクトのproduces定義を上書きします。グローバル定義をクリアするために空の値を使用することもできます。値はMIMEタイプに記載されているとおりである必要があります。
パラメーター [パラメータオブジェクト | 参照オブジェクト] この操作に適用可能なパラメータのリスト。パラメータがすでにパスアイテムで定義されている場合、新しい定義はそれを上書きしますが、削除することはできません。リストには重複するパラメータを含めることはできません。一意のパラメータは、名前と場所の組み合わせで定義されます。リストは、Swaggerオブジェクトのパラメータで定義されているパラメータにリンクするために参照オブジェクトを使用できます。最大で1つの「body」パラメータが存在できます。
レスポンス レスポンスオブジェクト 必須。 この操作の実行によって返される可能性のある応答のリスト。
スキーム [文字列] 操作の転送プロトコル。値は、"http"、"https"、"ws"、"wss"のリストから選択する必要があります。この値は、Swaggerオブジェクトのschemes定義を上書きします。
非推奨 ブール値 この操作が非推奨であることを宣言します。宣言された操作の使用は控えるべきです。デフォルト値はfalseです。
セキュリティ [セキュリティ要件オブジェクト] この操作に適用されるセキュリティスキームの宣言。値のリストは、使用できる代替セキュリティスキームを記述します（つまり、セキュリティ要件間に論理ORがあります）。この定義は、宣言された最上位のsecurityを上書きします。最上位のセキュリティ宣言を削除するには、空の配列を使用できます。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
オペレーションオブジェクトの例
{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "description": "",
  "operationId": "updatePetWithForm",
  "consumes": [
    "application/x-www-form-urlencoded"
  ],
  "produces": [
    "application/json",
    "application/xml"
  ],
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "type": "string"
    },
    {
      "name": "name",
      "in": "formData",
      "description": "Updated name of the pet",
      "required": false,
      "type": "string"
    },
    {
      "name": "status",
      "in": "formData",
      "description": "Updated status of the pet",
      "required": false,
      "type": "string"
    }
  ],
  "responses": {
    "200": {
      "description": "Pet updated."
    },
    "405": {
      "description": "Invalid input"
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  type: string
- name: name
  in: formData
  description: Updated name of the pet
  required: false
  type: string
- name: status
  in: formData
  description: Updated status of the pet
  required: false
  type: string
responses:
  '200':
    description: Pet updated.
  '405':
    description: Invalid input
security:
- petstore_auth:
  - write:pets
  - read:pets

外部ドキュメンテーションオブジェクト

拡張ドキュメントのために外部リソースを参照することを許可します。

固定フィールド
フィールド名 タイプ 説明
説明 文字列 ターゲットドキュメントの簡単な説明。GFM構文を使用してリッチテキスト表現にすることができます。
URL 文字列 必須。 ターゲットドキュメントのURL。値はURL形式である必要があります。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
外部ドキュメンテーションオブジェクトの例
{
  "description": "Find more info here",
  "url": "https://swagger.dokyumento.jp"
}

description: Find more info here
url: https://swagger.dokyumento.jp

パラメーターオブジェクト

単一の操作パラメータを記述します。

一意のパラメータは、名前と場所の組み合わせで定義されます。

5つの可能なパラメータタイプがあります。

  • パス - パスのテンプレート化と組み合わせて使用され、パラメータ値は実際に操作のURLの一部です。これにはAPIのホストやベースパスは含まれません。たとえば、/items/{itemId}では、パスパラメータはitemIdです。
  • クエリ - URLに追加されるパラメータ。例えば、/items?id=###の場合、クエリパラメータはidです。
  • ヘッダー - リクエストの一部として期待されるカスタムヘッダー。
  • Body - HTTPリクエストに追加されるペイロード。ペイロードは1つしか存在できないため、ボディパラメータも**1つ**しか存在できません。ボディパラメータの名前はパラメータ自体には影響せず、ドキュメンテーション目的でのみ使用されます。フォームパラメータもペイロードに含まれるため、同じ操作に対してボディパラメータとフォームパラメータを同時に宣言することはできません。
  • フォーム - HTTPリクエストのペイロードを記述するために使用され、application/x-www-form-urlencoded、multipart/form-data、またはその両方がリクエストのコンテンツタイプ（Swaggerの定義では、操作のconsumesプロパティ）として使用されます。これはファイルを送信するために使用できる唯一のパラメータタイプであり、fileタイプをサポートします。フォームパラメータはペイロードで送信されるため、同じ操作に対してボディパラメータと一緒に宣言することはできません。フォームパラメータは使用されるコンテンツタイプに基づいて異なる形式を持ちます（詳細については、http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4を参照）。
    • application/x-www-form-urlencoded - クエリパラメータの形式に似ていますが、ペイロードとして使用されます。たとえば、foo=1&bar=swaggerの場合、fooとbarの両方がフォームパラメータです。これは通常、転送される単純なパラメータに使用されます。
    • multipart/form-data - 各パラメータは、内部ヘッダーを持つペイロードのセクションを取ります。たとえば、ヘッダーContent-Disposition: form-data; name="submit-name"の場合、パラメータの名前はsubmit-nameです。このタイプのフォームパラメータは、ファイルの転送によく使用されます。
固定フィールド
フィールド名 タイプ 説明
名前 文字列 必須。 パラメータの名前。パラメータ名は**大文字と小文字を区別します**。
  • inが"path"の場合、nameフィールドはパスオブジェクトのパスフィールドの関連するパスセグメントに対応する必要があります。パスのテンプレート化の詳細については、そちらを参照してください。
  • その他のすべてのケースでは、nameはinプロパティに基づいて使用されるパラメータ名に対応します。
イン 文字列 必須。 パラメータの場所。可能な値は「query」、「header」、「path」、「formData」、または「body」です。
説明 文字列 パラメータの簡単な説明。使用例が含まれる場合があります。GFM構文を使用してリッチテキスト表現にすることができます。
必須 ブール値 このパラメータが必須かどうかを決定します。パラメータが「path」にinである場合、このプロパティは**必須**であり、その値はtrueでなければなりません。それ以外の場合、このプロパティは含めてもよく、そのデフォルト値はfalseです。

inが"body"の場合

フィールド名 タイプ 説明
スキーマ スキーマオブジェクト 必須。 ボディパラメータに使用される型を定義するスキーマ。

inが"body"以外の値である場合

フィールド名 タイプ 説明
タイプ 文字列 必須。 パラメータの型。パラメータはリクエストボディには配置されないため、単純な型（つまり、オブジェクトではない）に限定されます。値は、"string"、"number"、"integer"、"boolean"、"array"、または"file"のいずれかでなければなりません。typeが"file"の場合、consumesは"multipart/form-data"、"application/x-www-form-urlencoded"、またはその両方でなければならず、パラメータは"formData"にinでなければなりません。
フォーマット 文字列 前述のtypeの拡張フォーマット。データ型フォーマットの詳細については、そちらを参照してください。
allowEmptyValue ブール値 空値のパラメータを渡す機能を設定します。これはqueryまたはformDataパラメータにのみ有効で、名前のみまたは空の値を持つパラメータを送信できます。デフォルト値はfalseです。
アイテム アイテムオブジェクト typeが「array」の場合に必須。 配列内の項目の型を記述します。
コレクションフォーマット 文字列 タイプ配列が使用されている場合の配列のフォーマットを決定します。可能な値は次のとおりです
  • csv - コンマ区切り値 foo,bar。
  • ssv - スペース区切り値 foo bar。
  • tsv - タブ区切り値 foo\tbar。
  • pipes - パイプ区切り値 foo|bar。
  • multi - 単一のインスタンスの複数の値ではなく、複数のパラメータインスタンスに対応します foo=bar&foo=baz。これは、「query」または「formData」のinのパラメータにのみ有効です。
デフォルト値はcsvです。
デフォルト * 提供されない場合にサーバーが使用するパラメータの値を宣言します。例えば、ページごとの結果数を制御する「count」は、クライアントによってリクエストで提供されない場合、デフォルトで100になるかもしれません。（注：「default」は必須パラメータには意味がありません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照。JSON Schemaとは異なり、この値は、このパラメータに対して定義されたtypeに準拠しなければなりません。
最大 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
排他的最大 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
最小 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
排他的最小 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
最大長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照。
最小長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照。
パターン 文字列 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3を参照。
maxItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2を参照。
minItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3を参照。
uniqueItems ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4を参照。
列挙型 [*] https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1を参照。
multipleOf 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1を参照。
パターン化されたフィールド
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
パラメーターオブジェクトの例
ボディパラメーター

参照スキーマ定義（通常はモデル定義用）を持つボディパラメータ

{
  "name": "user",
  "in": "body",
  "description": "user to add to the system",
  "required": true,
  "schema": {
    "$ref": "#/definitions/User"
  }
}

name: user
in: body
description: user to add to the system
required: true
schema:
  $ref: '#/definitions/User'

文字列値の配列であるボディパラメータ

{
  "name": "user",
  "in": "body",
  "description": "user to add to the system",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

name: user
in: body
description: user to add to the system
required: true
schema:
  type: array
  items:
    type: string
その他のパラメーター

64ビット整数値の配列を持つヘッダーパラメータ

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "type": "array",
  "items": {
    "type": "integer",
    "format": "int64"
  },
  "collectionFormat": "csv"
}

name: token
in: header
description: token to be passed as a header
required: true
type: array
items:
  type: integer
  format: int64
collectionFormat: csv

文字列値のパスパラメータ

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "type": "string"
}

name: username
in: path
description: username to fetch
required: true
type: string

クエリパラメータを繰り返すことで複数の値を許可する、文字列値のオプションのクエリパラメータ

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "type": "array",
  "items": {
    "type": "string"
  },
  "collectionFormat": "multi"
}

name: id
in: query
description: ID of the object to fetch
required: false
type: array
items:
  type: string
collectionFormat: multi

ファイルアップロード用のファイルタイプを持つフォームデータ

{
  "name": "avatar",
  "in": "formData",
  "description": "The avatar of the user",
  "required": true,
  "type": "file"
}

name: avatar
in: formData
description: The avatar of the user
required: true
type: file

アイテムオブジェクト

JSON-Schemaのアイテムオブジェクトの限定されたサブセット。これは、"body"にinとして配置されていないパラメータ定義によって使用されます。

固定フィールド
フィールド名 タイプ 説明
タイプ 文字列 必須。 配列の内部型。値は、"string"、"number"、"integer"、"boolean"、または"array"のいずれかでなければなりません。ファイルとモデルは許可されていません。
フォーマット 文字列 前述のtypeの拡張フォーマット。データ型フォーマットの詳細については、そちらを参照してください。
アイテム アイテムオブジェクト typeが「array」の場合に必須。 配列内の項目の型を記述します。
コレクションフォーマット 文字列 タイプ配列が使用されている場合の配列のフォーマットを決定します。可能な値は次のとおりです
  • csv - コンマ区切り値 foo,bar。
  • ssv - スペース区切り値 foo bar。
  • tsv - タブ区切り値 foo\tbar。
  • pipes - パイプ区切り値 foo|bar。
デフォルト値はcsvです。
デフォルト * 何も提供されない場合にサーバーが使用する項目の値を宣言します。（注：「default」は必須項目には意味がありません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照。JSON Schemaとは異なり、この値はデータ型の定義されたtypeに準拠しなければなりません。
最大 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
排他的最大 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
最小 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
排他的最小 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
最大長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照。
最小長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照。
パターン 文字列 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3を参照。
maxItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2を参照。
minItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3を参照。
uniqueItems ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4を参照。
列挙型 [*] https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1を参照。
multipleOf 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1を参照。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
アイテムオブジェクトの例

アイテムは文字列型で、最小長は2文字でなければなりません。

{
    "type": "string",
    "minLength": 2
}

type: string
minLength: 2

配列の配列で、内部配列は整数型であり、数値は0から63（両端を含む）の間でなければなりません。

{
    "type": "array",
    "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 63
    }
}

type: array
items:
  type: integer
  minimum: 0
  maximum: 63

レスポンスオブジェクト

操作の予期される応答のコンテナ。コンテナはHTTP応答コードを予期される応答にマッピングします。HTTP応答コードは事前にすべてを知ることはできないため、ドキュメントがすべての可能なHTTP応答コードをカバーする必要があるとは期待されません。ただし、成功した操作応答と既知のエラーをドキュメントがカバーすることは期待されます。

defaultは、仕様で個別にカバーされていないすべてのHTTPコードのデフォルト応答オブジェクトとして使用できます。

Responses Objectは少なくとも1つの応答コードを含んでいなければならず、それは成功した操作呼び出しに対する応答であるべきです。

固定フィールド
フィールド名 タイプ 説明
デフォルト レスポンスオブジェクト | 参照オブジェクト 特定のHTTP応答コードに対して宣言された応答以外の応答のドキュメント。宣言されていない応答をカバーするために使用できます。参照オブジェクトは、Swaggerオブジェクトの応答セクションで定義されている応答にリンクするために使用できます。
パターン化されたフィールド
フィールドパターン タイプ 説明
{HTTPステータスコード} レスポンスオブジェクト | 参照オブジェクト 任意のHTTPステータスコードをプロパティ名として使用できます（HTTPステータスコードごとに1つのプロパティ）。そのHTTPステータスコードの予期される応答を記述します。参照オブジェクトは、Swaggerオブジェクトの応答セクションで定義されている応答にリンクするために使用できます。
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
レスポンスオブジェクトの例

成功した操作に対する200レスポンスと、その他のデフォルトレスポンス（エラーを意味する）

{
  "200": {
    "description": "a pet to be returned",
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  },
  "default": {
    "description": "Unexpected error",
    "schema": {
      "$ref": "#/definitions/ErrorModel"
    }
  }
}

'200':
  description: a pet to be returned
  schema:
    $ref: '#/definitions/Pet'
default:
  description: Unexpected error
  schema:
    $ref: '#/definitions/ErrorModel'

レスポンスオブジェクト

API操作からの単一の応答を記述します。

固定フィールド
フィールド名 タイプ 説明
説明 文字列 必須。 レスポンスの簡単な説明。GFM構文を使用してリッチテキスト表現にすることができます。
スキーマ スキーマオブジェクト 応答構造の定義。これはプリミティブ、配列、またはオブジェクトにすることができます。このフィールドが存在しない場合、応答の一部としてコンテンツが返されないことを意味します。スキーマオブジェクトの拡張として、そのルートtype値は"file"でも構いません。これには関連するproduces MIMEタイプが付随するべきです。
ヘッダー ヘッダーオブジェクト 応答とともに送信されるヘッダーのリスト。
例 例オブジェクト 応答メッセージの例。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
レスポンスオブジェクトの例

複雑な型の配列の応答

{
  "description": "A complex object array response",
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/VeryComplexType"
    }
  }
}

description: A complex object array response
schema:
  type: array
  items:
    $ref: '#/definitions/VeryComplexType'

文字列型の応答

{
  "description": "A simple string response",
  "schema": {
    "type": "string"
  }
}

description: A simple string response
schema:
  type: string

ヘッダー付きレスポンス

{
  "description": "A simple string response",
  "schema": {
    "type": "string"
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "type": "integer"
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "type": "integer"
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "type": "integer"
    }
  }
}

description: A simple string response
schema:
  type: string
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    type: integer

戻り値のない応答

{
  "description": "object created"
}

description: object created

ヘッダーオブジェクト

応答の一部として送信できるヘッダーをリストします。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} ヘッダーオブジェクト プロパティの名前はヘッダーの名前に対応します。値はヘッダーのタイプを記述します。
ヘッダーオブジェクトの例

レート制限ヘッダー

{
    "X-Rate-Limit-Limit": {
        "description": "The number of allowed requests in the current period",
        "type": "integer"
    },
    "X-Rate-Limit-Remaining": {
        "description": "The number of remaining requests in the current period",
        "type": "integer"
    },
    "X-Rate-Limit-Reset": {
        "description": "The number of seconds left in the current period",
        "type": "integer"
    }
}

X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  type: integer
X-Rate-Limit-Remaining:
  description: The number of remaining requests in the current period
  type: integer
X-Rate-Limit-Reset:
  description: The number of seconds left in the current period
  type: integer

例オブジェクト

操作応答の例を共有できるようにします。

パターン化されたフィールド
フィールドパターン タイプ 説明
{MIMEタイプ} Any プロパティの名前は、操作のproduces値のいずれか（暗黙的または継承されたもの）でなければなりません。値は、そのような応答がどのようなものになるかの例であるべきです。
例オブジェクトの例

Petデータ型のapplication/json mimetypeに対する応答例

{
  "application/json": {
    "name": "Puma",
    "type": "Dog",
    "color": "Black",
    "gender": "Female",
    "breed": "Mixed"
  }
}

application/json:
  name: Puma
  type: Dog
  color: Black
  gender: Female
  breed: Mixed

ヘッダーオブジェクト

フィールド名 タイプ 説明
説明 文字列 ヘッダーの簡単な説明。
タイプ 文字列 必須。 オブジェクトの型。値は、"string"、"number"、"integer"、"boolean"、または"array"のいずれかでなければなりません。
フォーマット 文字列 前述のtypeの拡張フォーマット。データ型フォーマットの詳細については、そちらを参照してください。
アイテム アイテムオブジェクト typeが「array」の場合に必須。 配列内の項目の型を記述します。
コレクションフォーマット 文字列 タイプ配列が使用されている場合の配列のフォーマットを決定します。可能な値は次のとおりです
  • csv - コンマ区切り値 foo,bar。
  • ssv - スペース区切り値 foo bar。
  • tsv - タブ区切り値 foo\tbar。
  • pipes - パイプ区切り値 foo|bar。
デフォルト値はcsvです。
デフォルト * 提供されない場合にサーバーが使用するヘッダーの値を宣言します。（注：「default」は必須ヘッダーには意味がありません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照。JSON Schemaとは異なり、この値はヘッダーに定義されたtypeに準拠しなければなりません。
最大 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
排他的最大 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照。
最小 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
排他的最小 ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照。
最大長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照。
最小長 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照。
パターン 文字列 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3を参照。
maxItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2を参照。
minItems 整数 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3を参照。
uniqueItems ブール値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
列挙型 [*] https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1を参照。
multipleOf 数値 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1を参照。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
ヘッダーオブジェクトの例

整数型のシンプルなヘッダー

{
  "description": "The number of allowed requests in the current period",
  "type": "integer"
}

description: The number of allowed requests in the current period
type: integer

タグオブジェクト

操作オブジェクトで使用される単一のタグにメタデータを追加できるようにします。使用されるタグごとにタグオブジェクトを持つことは必須ではありません。

固定フィールド
フィールド名 タイプ 説明
名前 文字列 必須。 タグの名前。
説明 文字列 タグの簡単な説明。GFM構文を使用してリッチテキスト表現にすることができます。
外部ドキュメント 外部ドキュメンテーションオブジェクト このタグの追加の外部ドキュメント。
パターン化されたフィールド
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
タグオブジェクトの例
{
	"name": "pet",
	"description": "Pets operations"
}

name: pet
description: Pets operations

参照オブジェクト

仕様内の他の定義を参照できるようにするシンプルなオブジェクト。再利用のために最上位で定義されているパラメータや応答を参照するために使用できます。

参照オブジェクトは、その値としてJSONポインタを使用するJSON参照です。この仕様では、正規の参照解除のみがサポートされています。

固定フィールド
フィールド名 タイプ 説明
$ref 文字列 必須。 参照文字列。
参照オブジェクトの例
{
	"$ref": "#/definitions/Pet"
}

$ref: '#/definitions/Pet'
相対スキーマファイルの例
{
  "$ref": "Pet.json"
}

$ref: 'Pet.yaml'
埋め込みスキーマを含む相対ファイルの例
{
  "$ref": "definitions.json#/Pet"
}

$ref: 'definitions.yaml#/Pet'

スキーマオブジェクト

Schema Objectは、入力および出力データ型の定義を可能にします。これらの型はオブジェクトだけでなく、プリミティブや配列も可能です。このオブジェクトはJSON Schema Specification Draft 4に基づいており、その定義済みサブセットを使用しています。このサブセットに加えて、より完全なドキュメンテーションを可能にするために、この仕様によって拡張機能が提供されています。

プロパティの詳細については、JSON Schema CoreおよびJSON Schema Validationを参照してください。特に明記されていない限り、プロパティ定義はここで参照されているJSON Schema仕様に従います。

以下のプロパティはJSON Schema定義から直接取得され、同じ仕様に従います。

  • $ref - JSON Referenceとして
  • フォーマット（詳細についてはデータ型フォーマットを参照）
  • タイトル
  • 説明（GFM構文を使用してリッチテキスト表現にすることができます）
  • デフォルト（JSON Schemaとは異なり、値はSchema Objectの定義された型に準拠する必要があります）
  • multipleOf
  • 最大
  • 排他的最大
  • 最小
  • 排他的最小
  • 最大長
  • 最小長
  • パターン
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • 必須
  • 列挙型
  • タイプ

以下のプロパティはJSON Schema定義から取得されていますが、その定義はSwagger Specificationに合わせて調整されています。元の定義がJSON Schema定義を参照している箇所では、代わりにSchema Object定義が使用されている点を除けば、その定義はJSON Schemaと同じです。

  • アイテム
  • allOf
  • プロパティ
  • 追加プロパティ

JSON Schemaサブセットフィールド以外にも、以下のフィールドはスキーマのさらなるドキュメントに使用できます。

固定フィールド
フィールド名 タイプ 説明
差別化要因 文字列 ポリモーフィズムのサポートを追加します。discriminatorは、このスキーマを継承する他のスキーマを区別するために使用されるスキーマプロパティ名です。使用されるプロパティ名は、このスキーマで定義され、requiredプロパティリストに存在する必要があります。使用される場合、値は、このスキーマまたはそれを継承する任意のスキーマの名前である必要があります。
読み取り専用 ブール値 スキーマ"properties"定義にのみ関連します。プロパティを「読み取り専用」として宣言します。これは、応答の一部として送信されることは許可されるが、要求の一部として送信されることは許可されないことを意味します。readOnlyがtrueとしてマークされたプロパティは、定義されたスキーマのrequiredリストに含めるべきではありません。デフォルト値はfalseです。
xml XMLオブジェクト これはプロパティスキーマでのみ使用できます。ルートスキーマには影響しません。このプロパティのXML表現形式を記述するための追加のメタデータを追加します。
外部ドキュメント 外部ドキュメンテーションオブジェクト このスキーマに関する追加の外部ドキュメント。
例 Any このスキーマのインスタンスの例を含めるための自由形式のプロパティ。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
構成と継承（ポリモーフィズム）

Swaggerは、JSON SchemaのallOfプロパティを使用してモデル定義を結合および拡張することを許可し、実質的にモデル構成を提供します。allOfは、**独立して**検証されるが、結合されて単一のオブジェクトを構成するオブジェクト定義の配列を受け取ります。

構成はモデルの拡張性を提供しますが、モデル間の階層は意味しません。ポリモーフィズムをサポートするために、Swaggerはdiscriminatorフィールドのサポートを追加します。使用される場合、discriminatorは、モデルの構造を検証するためにどのスキーマ定義が使用されるかを決定するプロパティの名前になります。したがって、discriminatorフィールドは必須フィールドである必要があります。選択されたプロパティの値は、definitionsプロパティの下のモデルに与えられたフレンドリ名である必要があります。したがって、与えられたIDを持たないインラインスキーマ定義は、ポリモーフィズムでは**使用できません**。

XMLモデリング

xmlプロパティは、JSON定義をXMLに変換する際の追加定義を可能にします。XMLオブジェクトには、利用可能なオプションに関する追加情報が含まれています。

スキーマオブジェクトの例
プリミティブサンプル

以前のバージョンのSwaggerとは異なり、スキーマ定義はプリミティブや配列も記述するために使用できます。

{
    "type": "string",
    "format": "email"
}

type: string
format: email
シンプルなモデル
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/definitions/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/definitions/Address'
  age:
    type: integer
    format: int32
    minimum: 0
マップ/辞書プロパティを持つモデル

シンプルな文字列から文字列へのマッピングの場合

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

文字列からモデルへのマッピングの場合

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/definitions/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'
例付きモデル
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1
構成を持つモデル
{
  "definitions": {
    "ErrorModel": {
      "type": "object",
      "required": [
        "message",
        "code"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "code": {
          "type": "integer",
          "minimum": 100,
          "maximum": 600
        }
      }
    },
    "ExtendedErrorModel": {
      "allOf": [
        {
          "$ref": "#/definitions/ErrorModel"
        },
        {
          "type": "object",
          "required": [
            "rootCause"
          ],
          "properties": {
            "rootCause": {
              "type": "string"
            }
          }
        }
      ]
    }
  }
}

definitions:
  ErrorModel:
    type: object
    required:
    - message
    - code
    properties:
      message:
        type: string
      code:
        type: integer
        minimum: 100
        maximum: 600
  ExtendedErrorModel:
    allOf:
    - $ref: '#/definitions/ErrorModel'
    - type: object
      required:
      - rootCause
      properties:
        rootCause:
          type: string
ポリモーフィズムをサポートするモデル
{
  "definitions": {
    "Pet": {
      "type": "object",
      "discriminator": "petType",
      "properties": {
        "name": {
          "type": "string"
        },
        "petType": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "petType"
      ]
    },
    "Cat": {
      "description": "A representation of a cat",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "huntingSkill": {
              "type": "string",
              "description": "The measured skill for hunting",
              "default": "lazy",
              "enum": [
                "clueless",
                "lazy",
                "adventurous",
                "aggressive"
              ]
            }
          },
          "required": [
            "huntingSkill"
          ]
        }
      ]
    },
    "Dog": {
      "description": "A representation of a dog",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "packSize": {
              "type": "integer",
              "format": "int32",
              "description": "the size of the pack the dog is from",
              "default": 0,
              "minimum": 0
            }
          },
          "required": [
            "packSize"
          ]
        }
      ]
    }
  }
}

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize

XMLオブジェクト

よりきめ細かいXMLモデル定義を可能にするメタデータオブジェクト。

配列を使用する場合、XML要素名は（単数形/複数形のために）**推測されず**、その情報を追加するためにnameプロパティを使用する必要があります。期待される動作については例を参照してください。

固定フィールド
フィールド名 タイプ 説明
名前 文字列 記述されたスキーマプロパティに使用される要素/属性の名前を置き換えます。Items Object (items) 内で定義されている場合、リスト内の個々のXML要素の名前に影響します。typeがarray (itemsの外側) とともに定義されている場合、ラッパー要素に影響し、wrappedがtrueの場合にのみ影響します。wrappedがfalseの場合、無視されます。
ネームスペース 文字列 名前空間定義のURL。値はURL形式であるべきです。
プレフィックス 文字列 名前に使用するプレフィックス。
属性 ブール値 プロパティ定義が要素ではなく属性に変換されるかどうかを宣言します。デフォルト値はfalseです。
包まれた ブール値 配列定義にのみ使用できます。配列がラップされているか（例：<books><book/><book/></books>）、ラップされていないか（<book/><book/>）を示します。デフォルト値はfalseです。この定義は、typeがarrayと同時に定義されている場合にのみ有効です（itemsの外側）。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
XMLオブジェクトの例

XMLオブジェクト定義の例は、スキーマオブジェクトのプロパティ定義内に、XML表現のサンプルとともに含まれています。

XML要素なし

基本的な文字列プロパティ

{
    "animals": {
        "type": "string"
    }
}

animals:
  type: string

<animals>...</animals>

基本的な文字列配列プロパティ（wrappedはデフォルトでfalseです）

{
    "animals": {
        "type": "array",
        "items": {
            "type": "string"
        }
    }
}

animals:
  type: array
  items:
    type: string

<animals>...</animals>
<animals>...</animals>
<animals>...</animals>
XML名の置換
{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>
XML属性、プレフィックス、および名前空間

この例では、完全なモデル定義が示されています。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://swagger.dokyumento.jp/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://swagger.dokyumento.jp/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://swagger.dokyumento.jp/schema/sample">example</sample:name>
</Person>
XML配列

要素名の変更

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animal>value</animal>
<animal>value</animal>

外部のnameプロパティはXMLに影響しません。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animal>value</animal>
<animal>value</animal>

配列がラップされていても、名前が明示的に定義されていない場合、内部的にも外部的にも同じ名前が使用されます。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

上記の例を解決するには、以下の定義を使用できます。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

内部名と外部名の両方に影響を与える

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

外部要素を変更しても内部要素を変更しない場合

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

定義オブジェクト

操作によって消費および生成できるデータ型を保持するオブジェクト。これらのデータ型はプリミティブ、配列、またはモデルにすることができます。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} スキーマオブジェクト 単一の定義で、「名前」をそれが定義するスキーマにマッピングします。
定義オブジェクトの例
{
  "Category": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "Tag": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    }
  }
}

Category:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
Tag:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string

パラメーター定義オブジェクト

操作間で再利用されるパラメーターを保持するオブジェクト。パラメーター定義は、ここで定義されているパラメーターを参照できます。

これは、グローバル操作パラメータを**定義しません**。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} パラメーターオブジェクト 単一のパラメータ定義で、「名前」をそれが定義するパラメータにマッピングします。
パラメーター定義オブジェクトの例
{
  "skipParam": {
    "name": "skip",
    "in": "query",
    "description": "number of items to skip",
    "required": true,
    "type": "integer",
    "format": "int32"
  },
  "limitParam": {
    "name": "limit",
    "in": "query",
    "description": "max records to return",
    "required": true,
    "type": "integer",
    "format": "int32"
  }
}

skipParam:
  name: skip
  in: query
  description: number of items to skip
  required: true
  type: integer
  format: int32
limitParam:
  name: limit
  in: query
  description: max records to return
  required: true
  type: integer
  format: int32

レスポンス定義オブジェクト

操作全体で再利用されるレスポンスを保持するオブジェクト。レスポンス定義は、ここで定義されているレスポンスを参照できます。

これは、グローバル操作応答を**定義しません**。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} レスポンスオブジェクト 単一のレスポンス定義で、「名前」をそれが定義するレスポンスにマッピングします。
レスポンス定義オブジェクトの例
{
  "NotFound": {
    "description": "Entity not found."
  },
  "IllegalInput": {
  	"description": "Illegal input for operation."
  },
  "GeneralError": {
  	"description": "General Error",
  	"schema": {
  		"$ref": "#/definitions/GeneralError"
  	}
  }
}

NotFound:
  description: Entity not found.
IllegalInput:
  description: Illegal input for operation.
GeneralError:
  description: General Error
  schema:
    $ref: '#/definitions/GeneralError'

セキュリティ定義オブジェクト

仕様で使用できるセキュリティスキームの宣言。これは操作にセキュリティスキームを強制するものではなく、各スキームに関連する詳細を提供するだけのものです。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} セキュリティスキームオブジェクト 単一のセキュリティスキーム定義で、「名前」をそれが定義するスキームにマッピングします。
セキュリティ定義オブジェクトの例
{
  "api_key": {
    "type": "apiKey",
    "name": "api_key",
    "in": "header"
  },
  "petstore_auth": {
    "type": "oauth2",
    "authorizationUrl": "https://swagger.dokyumento.jp/api/oauth/dialog",
    "flow": "implicit",
    "scopes": {
      "write:pets": "modify pets in your account",
      "read:pets": "read your pets"
    }
  }
}

api_key:
  type: apiKey
  name: api_key
  in: header
petstore_auth:
  type: oauth2
  authorizationUrl: https://swagger.dokyumento.jp/api/oauth/dialog
  flow: implicit
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets

セキュリティスキームオブジェクト

操作で使用できるセキュリティスキームの定義を許可します。サポートされているスキームは、基本認証、APIキー（ヘッダーまたはクエリパラメータのいずれか）、OAuth2の一般的なフロー（implicit、password、application、access code）です。

固定フィールド
フィールド名 タイプ 有効性 説明
タイプ 文字列 Any 必須。 セキュリティスキームのタイプ。有効な値は"basic"、"apiKey"、または"oauth2"です。
説明 文字列 Any セキュリティスキームの簡単な説明。
名前 文字列 APIキー 必須。 使用するヘッダーまたはクエリパラメータの名前。
イン 文字列 APIキー 必須 APIキーの場所。有効な値は"query"または"header"です。
フロー 文字列 oauth2 必須。 OAuth2セキュリティスキームで使用されるフロー。有効な値は、"implicit"、"password"、"application"、または"accessCode"です。
認可URL 文字列 oauth2 ("implicit", "accessCode") 必須。 このフローに使用される認証URL。URL形式であるべきです。
トークンURL 文字列 oauth2 ("password", "application", "accessCode") 必須。 このフローに使用されるトークンURL。URL形式であるべきです。
スコープ スコープオブジェクト oauth2 必須。 OAuth2セキュリティスキームで利用可能なスコープ。
パターン化されたフィールド
フィールド名 タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
セキュリティスキームオブジェクトの例
基本認証のサンプル
{
  "type": "basic"
}

type: basic
APIキーの例
{
  "type": "apiKey",
  "name": "api_key",
  "in": "header"
}

type: apiKey
name: api_key
in: header
Implicit OAuth2のサンプル
{
  "type": "oauth2",
  "authorizationUrl": "https://swagger.dokyumento.jp/api/oauth/dialog",
  "flow": "implicit",
  "scopes": {
    "write:pets": "modify pets in your account",
    "read:pets": "read your pets"
  }
}

type: oauth2
authorizationUrl: https://swagger.dokyumento.jp/api/oauth/dialog
flow: implicit
scopes:
  write:pets: modify pets in your account
  read:pets: read your pets

スコープオブジェクト

OAuth2セキュリティスキームで利用可能なスコープをリストします。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} 文字列 スコープの名前と、その簡単な説明（プロパティの値として）をマッピングします。
パターンオブジェクト
フィールドパターン タイプ 説明
^x- Any Swaggerスキーマの拡張を許可します。フィールド名はx-で始まる必要があります（例：x-internal-id）。値はnull、プリミティブ、配列、またはオブジェクトにすることができます。ベンダー拡張の詳細については、そちらを参照してください。
スコープオブジェクトの例
{
  "write:pets": "modify pets in your account",
  "read:pets": "read your pets"
}

write:pets: modify pets in your account
read:pets: read your pets

セキュリティ要件オブジェクト

この操作を実行するために必要なセキュリティスキームをリストします。このオブジェクトには複数のセキュリティスキームを宣言でき、それらはすべて必須です（つまり、スキーム間に論理ANDがあります）。

各プロパティに使用される名前は、セキュリティ定義で宣言されたセキュリティスキームに対応する必要があります。

パターン化されたフィールド
フィールドパターン タイプ 説明
{名前} [文字列] 各名前は、セキュリティ定義で宣言されているセキュリティスキームに対応する必要があります。セキュリティスキームのタイプが"oauth2"の場合、値は実行に必要なスコープ名のリストです。他のセキュリティスキームタイプの場合、配列は空である必要があります。
セキュリティ要件オブジェクトの例
OAuth2以外のセキュリティ要件
{
  "api_key": []
}

api_key: []
OAuth2セキュリティ要件
{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}

petstore_auth:
- write:pets
- read:pets

仕様の拡張

Swagger Specificationはほとんどのユースケースに対応しようとしますが、特定のポイントで仕様を拡張するために追加データを追加できます。

拡張プロパティは常に"x-"でプレフィックスされ、任意の有効なJSON形式の値を持つことができます。

拡張機能は、利用可能なツールによってサポートされている場合とされていない場合がありますが、要求されたサポートを追加するために拡張することもできます（ツールが内部またはオープンソースである場合）。

セキュリティフィルタリング

Swagger仕様内のいくつかのオブジェクトは、APIドキュメントの核となるものであっても、宣言されて空のままであったり、完全に削除されたりする場合があります。

その理由は、ドキュメント自体に追加のアクセス制御レイヤーを許可するためです。仕様自体の一部ではありませんが、特定のライブラリは、何らかの認証/認可形式に基づいてドキュメントの一部へのアクセスを許可することを選択する場合があります。

これに関する2つの例

  1. パスオブジェクトは空になる場合があります。これは直感に反するかもしれませんが、これにより閲覧者は正しい場所に到達したものの、ドキュメントにアクセスできないことを知ることができます。閲覧者は引き続き情報オブジェクトにアクセスでき、そこには認証に関する追加情報が含まれる場合があります。
  2. パスアイテムオブジェクトが空になる場合があります。この場合、閲覧者はパスが存在することを知っていますが、その操作やパラメータを見ることはできません。これは、パスオブジェクトからパス自体を隠すのとは異なり、ユーザーはパスの存在を知りません。これにより、ドキュメント提供者は閲覧者が見ることができるものに対してより細かい制御が可能になります。

© . This site is unofficial and not affiliated with Swagger.