OpenAPI 仕様

(旧Swagger RESTful APIドキュメント仕様)

バージョン 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ステータスコードレジストリで説明されています。

仕様

形式

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

たとえば、フィールドに配列値があるとされる場合、JSON配列表現が使用されます。

{
   "field" : [...]
}

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

仕様のすべてのフィールド名は、大文字と小文字が区別されます。

スキーマは2つのタイプのフィールドを公開します。宣言された名前を持つ固定フィールドと、フィールド名の正規表現パターンを宣言するパターン化されたフィールドです。パターン化されたフィールドは、それぞれが一意の名前を持つ限り、複数回発生する可能性があります。

ファイル構造

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

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

データ型

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

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

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

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

スキーマ

Swagger オブジェクト

これは、API仕様のルートドキュメントオブジェクトです。以前のリソースリストとAPI宣言（バージョン1.2以前）を1つのドキュメントにまとめたものです。

固定フィールド

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

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`null`、プリミティブ、配列、またはオブジェクトにできます。詳細については、ベンダー拡張を参照してください。

情報オブジェクト

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

固定フィールド

フィールド名	型	説明
title	`文字列`	必須。アプリケーションのタイトル。
description	`文字列`	アプリケーションの簡単な説明。GFM構文を使用して、リッチテキスト表現を使用できます。
termsOfService	`文字列`	APIの利用規約。
contact	連絡先オブジェクト	公開されたAPIの連絡先情報。
license	ライセンスオブジェクト	公開されたAPIのライセンス情報。
version	`文字列`	必須アプリケーションAPIのバージョンを提供します（仕様バージョンと混同しないでください）。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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の連絡先情報。

固定フィールド

フィールド名	型	説明
name	`文字列`	連絡担当者/組織を特定する名前。
url	`文字列`	連絡先情報を指すURL。URLの形式である必要があります。
email	`文字列`	連絡担当者/組織の電子メールアドレス。電子メールアドレスの形式である必要があります。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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のライセンス情報。

固定フィールド

フィールド名	型	説明
name	`文字列`	必須。 APIに使用されるライセンス名。
url	`文字列`	APIに使用されるライセンスへのURL。URLの形式である必要があります。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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

パスオブジェクト

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

パターン化されたフィールド

フィールドパターン	型	説明
/{path}	パスアイテムオブジェクト	個々のエンドポイントへの相対パス。フィールド名はスラッシュで始まる必要があります。パスは、完全なURLを構成するために`basePath`に追加されます。パステンプレートが許可されています。
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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	操作オブジェクト	このパスでのPUT操作の定義。
post	操作オブジェクト	このパスでのPOST操作の定義。
delete	操作オブジェクト	このパスでのDELETE操作の定義。
options	操作オブジェクト	このパスでのOPTIONS操作の定義。
head	操作オブジェクト	このパスでのHEAD操作の定義。
patch	操作オブジェクト	このパスでのPATCH操作の定義。
parameters	[パラメーターオブジェクト \| 参照オブジェクト]	このパスで記述されたすべての操作に適用可能なパラメーターのリスト。これらのパラメーターは操作レベルでオーバーライドできますが、そこで削除することはできません。リストに重複したパラメーターを含めてはなりません。一意のパラメーターは、nameとlocationの組み合わせによって定義されます。リストは、参照オブジェクトを使用して、Swaggerオブジェクトのパラメーターで定義されているパラメーターにリンクできます。最大で1つの「body」パラメーターが存在できます。

パターン化されたフィールド

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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操作について説明します。

固定フィールド

フィールド名	型	説明
tags	[`string`]	APIドキュメント制御用のタグのリスト。タグは、リソースまたはその他の修飾子による操作の論理的なグループ化に使用できます。
summary	`文字列`	操作の内容の簡単な概要。swagger-uiでの最大の読みやすさのために、このフィールドは120文字未満にする必要があります。
description	`文字列`	操作の動作の詳細な説明。GFM構文を使用して、リッチテキスト表現を使用できます。
externalDocs	外部ドキュメントオブジェクト	この操作に関する追加の外部ドキュメント。
operationId	`文字列`	操作を識別するために使用される一意の文字列。IDは、APIで記述されているすべての操作の中で一意である必要があります。ツールおよびライブラリは、操作を一意に識別するためにoperationIdを使用する可能性があるため、一般的なプログラミング命名規則に従うことをお勧めします。
consumes	[`string`]	操作が消費できるMIMEタイプのリスト。これは、Swaggerオブジェクトでの`consumes`定義を上書きします。空の値は、グローバル定義をクリアするために使用できます。値は、MIMEタイプで説明されているようにする必要があります。
produces	[`string`]	操作が生成できるMIMEタイプのリスト。これは、Swaggerオブジェクトでの`produces`定義を上書きします。空の値は、グローバル定義をクリアするために使用できます。値は、MIMEタイプで説明されているようにする必要があります。
parameters	[パラメーターオブジェクト \| 参照オブジェクト]	この操作に適用可能なパラメーターのリスト。パラメーターがパスアイテムで既に定義されている場合、新しい定義はそれをオーバーライドしますが、削除することはできません。リストに重複したパラメーターを含めてはなりません。一意のパラメーターは、nameとlocationの組み合わせによって定義されます。リストは、参照オブジェクトを使用して、Swaggerオブジェクトのパラメーターで定義されているパラメーターにリンクできます。最大で1つの「body」パラメーターが存在できます。
responses	応答オブジェクト	必須。この操作の実行から返される可能性のある応答のリスト。
schemes	[`string`]	操作の転送プロトコル。値は、リスト`"http"`、`"https"`、`"ws"`、`"wss"`からの値である必要があります。この値は、Swaggerオブジェクトの`schemes`定義をオーバーライドします。
deprecated	`ブール値`	この操作が非推奨であることを宣言します。宣言された操作の使用は控える必要があります。デフォルト値は`false`です。
security	[セキュリティ要件オブジェクト]	この操作に適用されるセキュリティスキームの宣言。値のリストは、使用できる代替セキュリティスキーム（つまり、セキュリティ要件間に論理ORがある）を記述します。この定義は、宣言されているトップレベルの`security`を上書きします。トップレベルのセキュリティ宣言を削除するには、空の配列を使用できます。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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

外部ドキュメントオブジェクト

拡張ドキュメントのために外部リソースを参照できるようにします。

固定フィールド

フィールド名	型	説明
description	`文字列`	ターゲットドキュメントの簡単な説明。GFM構文を使用して、リッチテキスト表現を使用できます。
url	`文字列`	必須。ターゲットドキュメントのURL。値はURLの形式である必要があります。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`null`、プリミティブ、配列、またはオブジェクトにできます。詳細については、ベンダー拡張を参照してください。

外部ドキュメントオブジェクトの例

{
  "description": "Find more info here",
  "url": "https://swagger.dokyumento.jp"
}

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

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

単一の操作パラメーターについて説明します。

一意のパラメーターは、nameとlocationの組み合わせによって定義されます。

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

Path - パステンプレートと一緒に使用されます。パラメーター値は、実際には操作のURLの一部です。これには、APIのホストまたはベースパスは含まれません。たとえば、/items/{itemId}では、パスパラメーターはitemIdです。
Query - URLに追加されるパラメーター。たとえば、/items?id=###では、クエリパラメーターはidです。
Header - リクエストの一部として予期されるカスタムヘッダー。
Body - HTTPリクエストに追加されるペイロード。ペイロードは1つしか存在できないため、bodyパラメーターは1つしか存在できません。bodyパラメーターの名前はパラメーター自体には影響せず、ドキュメントの目的でのみ使用されます。フォームパラメーターもペイロードにあるため、bodyパラメーターとフォームパラメーターを同じ操作で一緒に存在させることはできません。
フォーム - 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です。このタイプのフォームパラメータは、ファイル転送によく使用されます。

固定フィールド

フィールド名	型	説明
name	`文字列`	必須。パラメータの名前。パラメータ名は大文字と小文字を区別します。 `in` が `"path"` の場合、`name` フィールドは、path フィールドの関連するパスセグメントに対応する必要があります。詳しくはパスのテンプレートを参照してください。それ以外の場合、`name` は、`in` プロパティに基づいて使用されるパラメータ名に対応します。
in	`文字列`	必須。パラメータの場所。可能な値は、"query"、"header"、"path"、"formData"、または "body" です。
description	`文字列`	パラメータの簡単な説明。これには使用例が含まれる場合があります。GFM構文を使用して、リッチテキスト表現を使用できます。
required	`ブール値`	このパラメータが必須かどうかを決定します。パラメータが`in` "path" の場合、このプロパティは必須であり、その値は `true` である必要があります。それ以外の場合、プロパティを含めることができ、そのデフォルト値は `false` です。

in が "body" の場合

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

in が "body" 以外の値の場合

フィールド名	型	説明
type	`文字列`	必須。パラメータのタイプ。パラメータはリクエストボディに配置されないため、単純なタイプ（つまり、オブジェクトではない）に限定されます。値は、`"string"`、`"number"`、`"integer"`、`"boolean"`、`"array"`、または `"file"` のいずれかである必要があります。`type` が `"file"` の場合、`consumes` は、`"multipart/form-data"`、`" application/x-www-form-urlencoded"`、またはその両方である必要があり、パラメータは `in` `"formData"` である必要があります。
format	`文字列`	上記の`type`の拡張形式。詳細については、データ型形式を参照してください。
allowEmptyValue	`ブール値`	空の値のパラメータを渡す機能を設定します。これは、`query` または `formData` パラメータのいずれかでのみ有効であり、名前のみのパラメータまたは空の値を送信できます。デフォルト値は `false` です。
items	アイテムオブジェクト	`type`が "array" の場合は必須。配列内のアイテムのタイプを記述します。
collectionFormat	`文字列`	タイプ配列が使用されている場合の配列の形式を決定します。可能な値は次のとおりです。 `csv` - コンマ区切りの値 `foo,bar`。 `ssv` - スペース区切りの値 `foo bar`。 `tsv` - タブ区切りの値 `foo\tbar`。 `pipes` - パイプ区切りの値 `foo\|bar`。 `multi` - 単一のインスタンスに対する複数の値ではなく、複数のパラメータインスタンスに対応します `foo=bar&foo=baz`。これは、`in` "query" または "formData" のパラメータでのみ有効です。デフォルト値は `csv` です。
default	*	サーバーが何も提供されない場合に使用するパラメータの値を宣言します。たとえば、1ページあたりの結果数を制御する「count」は、クライアントがリクエストで提供しない場合、デフォルトで100になる場合があります。（注：「default」は必須パラメータには意味がありません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照してください。JSON Schemaとは異なり、この値は、このパラメータに定義された`type`に準拠する必要があります。
maximum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
exclusiveMaximum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
minimum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
exclusiveMinimum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
maxLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照してください。
minLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照してください。
pattern	`文字列`	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を参照してください。
enum	[*]	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-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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スキーマのitemsオブジェクトの限定されたサブセット。これは、in "body" に配置されていないパラメータ定義で使用されます。

固定フィールド

フィールド名	型	説明
type	`文字列`	必須。配列の内部タイプ。値は、`"string"`、`"number"`、`"integer"`、`"boolean"`、または `"array"` のいずれかである必要があります。ファイルとモデルは許可されていません。
format	`文字列`	上記の`type`の拡張形式。詳細については、データ型形式を参照してください。
items	アイテムオブジェクト	`type`が "array" の場合は必須。配列内のアイテムのタイプを記述します。
collectionFormat	`文字列`	タイプ配列が使用されている場合の配列の形式を決定します。可能な値は次のとおりです。 `csv` - コンマ区切りの値 `foo,bar`。 `ssv` - スペース区切りの値 `foo bar`。 `tsv` - タブ区切りの値 `foo\tbar`。 `pipes` - パイプ区切りの値 `foo\|bar`。デフォルト値は `csv` です。
default	*	何も提供されない場合にサーバーが使用するアイテムの値を宣言します。（注：「default」は必須アイテムには意味がありません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照してください。JSONスキーマとは異なり、この値はデータ型に対して定義された `type` に準拠する必要があります。
maximum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
exclusiveMaximum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
minimum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
exclusiveMinimum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
maxLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照してください。
minLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照してください。
pattern	`文字列`	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を参照してください。
enum	[*]	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-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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レスポンスコードを必ずしもカバーする必要はないと予想されます。ただし、ドキュメントは、成功した操作のレスポンスと既知のエラーをカバーすることが期待されます。

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

Responses Object は、少なくとも1つのレスポンスコードを含む必要があり、それは成功した操作呼び出しのレスポンスである必要があります。

固定フィールド

フィールド名	型	説明
default	レスポンスオブジェクト \| 参照オブジェクト	特定のHTTPレスポンスコードに対して宣言されたレスポンス以外のレスポンスのドキュメント。これは、未宣言のレスポンスをカバーするために使用できます。参照オブジェクトは、Swaggerオブジェクトのレスポンスセクションで定義されたレスポンスにリンクするために使用できます。

パターン化されたフィールド

フィールドパターン	型	説明
{HTTPステータスコード}	レスポンスオブジェクト \| 参照オブジェクト	任意のHTTPステータスコードをプロパティ名として使用できます（HTTPステータスコードごとに1つのプロパティ）。そのHTTPステータスコードに対して予期されるレスポンスを記述します。参照オブジェクトは、Swaggerオブジェクトのレスポンスセクションで定義されたレスポンスにリンクするために使用できます。
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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操作からの単一のレスポンスを記述します。

固定フィールド

フィールド名	型	説明
description	`文字列`	必須。レスポンスの簡単な説明。GFM構文を使用して、リッチテキスト表現を使用できます。
schema	スキーマオブジェクト	レスポンス構造の定義。プリミティブ型、配列、またはオブジェクトを指定できます。このフィールドが存在しない場合、レスポンスの一部としてコンテンツが返されないことを意味します。スキーマオブジェクトの拡張として、ルートの`type`値は`"file"`でも構いません。この場合、適切な`produces` MIME タイプを伴う必要があります。
headers	ヘッダーオブジェクト	レスポンスとともに送信されるヘッダーのリスト。
examples	例オブジェクト	レスポンスメッセージの例。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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

ヘッダーオブジェクト

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

パターン化されたフィールド

フィールドパターン	型	説明
{name}	ヘッダーオブジェクト	プロパティの名前は、ヘッダーの名前に対応します。値はヘッダーの型を表します。

ヘッダーオブジェクトの例

レート制限ヘッダー

{
    "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 タイプ}	任意	プロパティの名前は、操作の`produces`値（暗黙的または継承されたもの）のいずれかでなければなりません。値は、そのようなレスポンスがどのようなものかを示す例である必要があります。

例オブジェクトの例

Pet データ型の application/json MIME タイプに対するレスポンスの例

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

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

ヘッダーオブジェクト

フィールド名	型	説明
description	`文字列`	ヘッダーの簡単な説明。
type	`文字列`	必須。オブジェクトの型。値は、`"string"`、`"number"`、`"integer"`、`"boolean"`、または`"array"`のいずれかでなければなりません。
format	`文字列`	前述の`type`の拡張形式。詳細については、データ型フォーマットを参照してください。
items	アイテムオブジェクト	`type`が "array" の場合は必須。配列内の項目の型を記述します。
collectionFormat	`文字列`	タイプ配列が使用されている場合の配列の形式を決定します。可能な値は次のとおりです。 `csv` - コンマ区切りの値 `foo,bar`。 `ssv` - スペース区切りの値 `foo bar`。 `tsv` - タブ区切りの値 `foo\tbar`。 `pipes` - パイプ区切りの値 `foo\|bar`。デフォルト値は `csv` です。
default	*	ヘッダーが提供されない場合にサーバーが使用するヘッダーの値を宣言します。（注：必須ヘッダーの場合、「default」は意味を持ちません。）https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照してください。JSON Schema とは異なり、この値はヘッダーに対して定義された`type`に準拠する必要があります。
maximum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
exclusiveMaximum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。
minimum	`数値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
exclusiveMinimum	`ブール値`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。
maxLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照してください。
minLength	`整数`	https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照してください。
pattern	`文字列`	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.
enum	[*]	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-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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

タグオブジェクト

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

固定フィールド

フィールド名	型	説明
name	`文字列`	必須。タグの名前。
description	`文字列`	タグの簡単な説明。GFM 構文を使用して、リッチテキスト表現を使用できます。
externalDocs	外部ドキュメントオブジェクト	このタグの追加の外部ドキュメント。

パターン化されたフィールド

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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'

スキーマオブジェクト

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

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

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

$ref - JSON参照として
format (詳細についてはデータ型フォーマットを参照してください)
title
description (GFM構文を使用して、リッチテキスト表現を使用できます)
default (JSON Schema とは異なり、値はスキーマオブジェクトに対して定義された型に準拠する必要があります)
multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
maxLength
minLength
pattern
maxItems
minItems
uniqueItems
maxProperties
minProperties
required
enum
型

次のプロパティは JSON Schema 定義から取得されますが、Swagger 仕様に合わせて定義が調整されました。それらの定義は JSON Schema の定義と同じですが、元の定義が JSON Schema の定義を参照している場合にのみ、スキーマオブジェクトの定義が代わりに使用されます。

items
allOf
properties
additionalProperties

JSON Schema のサブセットフィールド以外に、次のフィールドをスキーマのドキュメントに使用できます。

固定フィールド

フィールド名	型	説明
discriminator	`文字列`	ポリモーフィズムのサポートを追加します。discriminator は、このスキーマを継承する他のスキーマを区別するために使用されるスキーマプロパティ名です。使用されるプロパティ名は、このスキーマで定義する必要があり、`required` プロパティリストにある必要があります。使用する場合、値はこのスキーマまたはそれを継承するスキーマの名前である必要があります。
readOnly	`ブール値`	スキーマの`"properties"`定義にのみ関連します。プロパティを「読み取り専用」として宣言します。これは、レスポンスの一部として送信される可能性がありますが、リクエストの一部として送信してはならないことを意味します。`readOnly`が`true`に設定されているプロパティは、定義されたスキーマの`required`リストに含まれるべきではありません。デフォルト値は`false`です。
xml	XMLオブジェクト	これは、プロパティスキーマでのみ使用できます。ルートスキーマには影響しません。このプロパティのXML表現形式を記述するための追加のメタデータを追加します。
externalDocs	外部ドキュメントオブジェクト	このスキーマの追加の外部ドキュメント。
example	任意	このスキーマのインスタンスの例を含めるための自由形式のプロパティ。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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 プロパティを使用してその情報を追加する必要があります。期待される動作の例を参照してください。

固定フィールド

フィールド名	型	説明
name	`文字列`	記述されたスキーマプロパティに使用される要素/属性の名前を置き換えます。アイテムオブジェクト（`items`）内で定義されている場合、リスト内の個々の XML 要素の名前に影響します。`type` が `array` である（`items` の外）と定義されている場合、ラッピング要素に影響し、`wrapped` が `true` の場合にのみ影響します。`wrapped` が `false` の場合は無視されます。
namespace	`文字列`	名前空間定義の URL。値は URL の形式である必要があります。
prefix	`文字列`	nameに使用されるプレフィックス。
attribute	`ブール値`	プロパティ定義が要素ではなく属性に変換されるかどうかを宣言します。デフォルト値は`false`です。
wrapped	`ブール値`	配列定義でのみ使用できます。配列がラップされている（たとえば、`<books><book/><book/></books>`）か、ラップされていない（`<book/><book/>`）かを示します。デフォルト値は`false`です。この定義は、`type` が `array` である（`items` の外）と定義されている場合にのみ有効になります。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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>

定義オブジェクト

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

パターン化されたフィールド

フィールドパターン	型	説明
{name}	スキーマオブジェクト	単一の定義で、「名前」をそれが定義するスキーマにマッピングします。

定義オブジェクトの例

{
  "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

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

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

これはグローバルな操作パラメータを定義するものではありません。

パターン化されたフィールド

フィールドパターン	型	説明
{name}	パラメーターオブジェクト	単一のパラメータ定義で、「name」をそれが定義するパラメータにマッピングします。

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

{
  "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

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

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

これはグローバルな操作レスポンスを定義するものではありません。

パターン化されたフィールド

フィールドパターン	型	説明
{name}	レスポンスオブジェクト	単一のレスポンス定義で、「name」をそれが定義するレスポンスにマッピングします。

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

{
  "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'

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

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

パターン化されたフィールド

フィールドパターン	型	説明
{name}	セキュリティスキームオブジェクト	単一のセキュリティスキーム定義で、「name」をそれが定義するスキームにマッピングします。

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

{
  "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の一般的なフロー（暗黙的、パスワード、アプリケーション、およびアクセスコード）です。

固定フィールド

フィールド名	型	有効性	説明
type	`文字列`	任意	必須。セキュリティスキームのタイプ。有効な値は`"basic"`、`"apiKey"`、または`"oauth2"`です。
description	`文字列`	任意	セキュリティスキームの簡単な説明。
name	`文字列`	`apiKey`	必須。使用するヘッダーまたはクエリパラメータの名前。
in	`文字列`	`apiKey`	必須 APIキーの場所。有効な値は`"query"`または`"header"`です。
flow	`文字列`	`oauth2`	必須。 OAuth2セキュリティスキームで使用されるフロー。有効な値は`"implicit"`、`"password"`、`"application"`、または`"accessCode"`です。
authorizationUrl	`文字列`	`oauth2` (`"implicit"`, `"accessCode"`)	必須。このフローで使用する認証URL。これはURL形式である必要があります。
tokenUrl	`文字列`	`oauth2` (`"password"`, `"application"`, `"accessCode"`)	必須。このフローで使用するトークンURL。これはURL形式である必要があります。
scopes	スコープオブジェクト	`oauth2`	必須。 OAuth2セキュリティスキームで使用可能なスコープ。

パターン化されたフィールド

フィールド名	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`null`、プリミティブ、配列、またはオブジェクトにできます。詳細については、ベンダー拡張を参照してください。

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

基本認証のサンプル

{
  "type": "basic"
}

type: basic

APIキーのサンプル

{
  "type": "apiKey",
  "name": "api_key",
  "in": "header"
}

type: apiKey
name: api_key
in: header

暗黙的な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セキュリティスキームで使用可能なスコープを一覧表示します。

パターン化されたフィールド

フィールドパターン	型	説明
{name}	`文字列`	スコープの名前と、その簡単な説明（プロパティの値として）との間をマッピングします。

パターン化されたオブジェクト

フィールドパターン	型	説明
^x-	任意	Swaggerスキーマの拡張を許可します。フィールド名は、例えば `x-internal-id` のように、`x-`で始まる必要があります。値は、`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が存在します）。

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

パターン化されたフィールド

フィールドパターン	型	説明
{name}	[`string`]	各名前は、セキュリティ定義で宣言されているセキュリティスキームに対応する必要があります。セキュリティスキームが`"oauth2"`型の場合、値は実行に必要なスコープ名のリストです。他のセキュリティスキームタイプの場合、配列は空である必要があります。

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

非OAuth2セキュリティ要件

{
  "api_key": []
}

api_key: []

OAuth2セキュリティ要件

{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}

petstore_auth:
- write:pets
- read:pets

仕様の拡張

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

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

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

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

Swagger仕様の一部のオブジェクトは、宣言されて空のままになったり、APIドキュメントの核となるものであっても、完全に削除されたりする可能性があります。

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

この2つの例

パスオブジェクトが空である可能性があります。直感的ではないかもしれませんが、これは、閲覧者が正しい場所に到達したが、ドキュメントにアクセスできないことを伝える可能性があります。それでも、認証に関する追加情報が含まれている可能性がある情報オブジェクトにアクセスできます。
パスアイテムオブジェクトが空である可能性があります。この場合、閲覧者はパスが存在することは認識しますが、操作やパラメータを表示することはできません。これは、パスオブジェクトからパス自体を非表示にして、ユーザーがその存在を認識しないようにすることとは異なります。これにより、ドキュメントプロバイダーは、閲覧者が表示できるものをより細かく制御できます。