OpenAPI 仕様

バージョン 3.1.0

このドキュメントで使用されているキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、および「OPTIONAL」は、BCP 14 RFC2119 RFC8174に記載されているように、すべて大文字で表示されている場合にのみ解釈されるものとします。

このドキュメントは、Apacheライセンスバージョン2.0の下でライセンスされています。

はじめに

OpenAPI仕様（OAS）は、ソースコード、ドキュメントへのアクセス、またはネットワークトラフィックの検査なしに、人間とコンピューターの両方がサービスの機能を検出および理解できるようにする、HTTPAPIへの標準的な言語に依存しないインターフェースを定義します。適切に定義されている場合、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、やり取りできます。

OpenAPI定義は、APIを表示するためのドキュメント生成ツール、さまざまなプログラミング言語でサーバーとクライアントを生成するためのコード生成ツール、テストツール、およびその他の多くのユースケースで使用できます。

定義

OpenAPIドキュメント

APIまたはAPIの要素を定義または記述する自己完結型または複合リソース。 OpenAPIドキュメントには、少なくとも1つのパスフィールド、コンポーネントフィールド、またはwebhookフィールドが含まれている必要があります。 OpenAPIドキュメントは、OpenAPI仕様を使用し、それに準拠します。

パステンプレート

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

パス内の各テンプレート式は、パスアイテム自体、または各パスアイテムの操作に含まれるパスパラメーターに対応している必要があります。例外は、パスアイテムが空の場合です。たとえば、ACL制約のため、一致するパスパラメーターは必須ではありません。

これらのパスパラメーターの値には、RFC3986で説明されているエスケープされていない「汎用構文」文字、つまりスラッシュ（/）、疑問符（?）、またはハッシュ（#）を含めることはできません。

メディアタイプ

メディアタイプの定義は、複数のリソースに分散しています。メディアタイプの定義は、RFC6838に準拠する必要があります。

可能なメディアタイプの定義のいくつかの例

  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ステータスコードは、実行された操作のステータスを示すために使用されます。利用可能なステータスコードは、RFC7231で定義されており、登録済みのステータスコードはIANAステータスコードレジストリにリストされています。

仕様

バージョン

OpenAPI仕様は、major。minor。patchバージョニングスキームを使用してバージョン管理されます。バージョン文字列のmajor。minor部分（例：3.1）は、OAS機能セットを指定します。 .patchバージョンは、機能セットではなく、このドキュメントのエラーに対処するか、明確化を提供します。 OAS 3.1をサポートするツールは、すべてのOAS3.1。*バージョンと互換性がある必要があります。パッチバージョンはツールによって考慮されるべきではなく、たとえば3.1.0と3.1.1を区別しません。

場合によっては、OASのminorバージョンで、提供されるメリットに対して影響が低いと判断される場合に、後方互換性のない変更が行われることがあります。

OAS 3。*。*と互換性のあるOpenAPIドキュメントには、使用するOASのバージョンを指定する必須のopenapiフィールドが含まれています。

フォーマット

OpenAPI仕様に準拠するOpenAPIドキュメント自体はJSONオブジェクトであり、JSONまたはYAML形式で表現できます。

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

{
   "field": [ 1, 2, 3 ]
}

仕様のすべてのフィールド名は、大文字と小文字が区別されます。これには、キーが大文字と小文字が区別されないことが明示的に注記されている場合を除き、マップでキーとして使用されるすべてのフィールドが含まれます。

スキーマは、宣言された名前を持つ固定フィールドと、フィールド名の正規表現パターンを宣言するパターン化されたフィールドの2種類のフィールドを公開します。

パターン化されたフィールドは、含まれているオブジェクト内で一意の名前を持っている必要があります。

YAMLとJSON形式の間でラウンドトリップする機能を維持するために、YAMLバージョン1.2といくつかの追加の制約を使用することをお勧めします。

タグは、JSONスキーマルールセットで許可されているものに限定する必要があります。
YAMLマップで使用されるキーは、YAMLフェイルセーフスキーマルールセットで定義されているように、スカラー文字列に制限する必要があります。

注：APIはYAMLまたはJSON形式のいずれかでOpenAPIドキュメントによって定義できますが、APIリクエストとレスポンスの本体およびその他のコンテンツは、JSONまたはYAMLである必要はありません。

ドキュメント構造

OpenAPIドキュメントは、単一のドキュメントで構成することも、作成者の裁量で複数の接続された部分に分割することもできます。後者の場合、参照オブジェクトとスキーマオブジェクト $refキーワードが使用されます。

ルートOpenAPIドキュメントは、openapi.jsonまたはopenapi.yamlという名前を付けることをお勧めします。

データ型

OASのデータ型は、JSONスキーマ仕様ドラフト2020-12でサポートされている型に基づいています。型としてのintegerもサポートされており、分数部または指数部なしのJSON数値として定義されていることに注意してください。モデルは、JSONスキーマ仕様ドラフト2020-12のスーパーセットであるスキーマオブジェクトを使用して定義されます。

JSONスキーマ検証語彙で定義されているように、データ型にはオプションの修飾子プロパティformatを含めることができます。 OASは、プリミティブデータ型に詳細を提供するために追加のフォーマットを定義します。

OASで定義されているフォーマットは次のとおりです。

`タイプ`	`フォーマット`	コメント
`整数`	`int32`	符号付き32ビット
`整数`	`int64`	符号付き64ビット（別名ロング）
`数値`	`フロート`
`数値`	`ダブル`
`文字列`	`パスワード`	UIに入力を隠すためのヒント。

リッチテキストフォーマット

この仕様全体を通して、description フィールドは CommonMark マークダウン形式をサポートすると記述されています。OpenAPIツールがリッチテキストをレンダリングする場合、少なくとも CommonMark 0.27 で記述されたマークダウン構文をサポートする必要があります。ツールは、セキュリティ上の懸念に対処するために、一部のCommonMark機能を無視することを選択しても構いません。

URIにおける相対参照

特に指定がない限り、URIであるすべてのプロパティは、RFC3986 で定義されている相対参照である可能性があります。

Reference Objects、PathItem Object の $ref フィールド、Link Object の operationRef フィールド、Example Object の externalValue フィールドを含む相対参照は、RFC3986 に従って、参照元のドキュメントをベースURIとして解決されます。

URIにフラグメント識別子が含まれている場合、フラグメントは参照先のドキュメントのフラグメント解決メカニズムに従って解決する必要があります。参照先のドキュメントの表現がJSONまたはYAMLである場合、フラグメント識別子は、RFC6901 に従ってJSONポインターとして解釈する必要があります。

Schema Objects 内の相対参照（$id 値として現れるものを含む）は、JSON Schema Specification Draft 2020-12 で説明されているように、最も近い親の $id をベースURIとして使用します。親スキーマに $id が含まれていない場合、ベースURIは RFC3986 に従って決定する必要があります。

URLにおける相対参照

特に指定がない限り、URLであるすべてのプロパティは、RFC3986 で定義されている相対参照である可能性があります。特に指定がない限り、相対参照は Server Object で定義されたURLをベースURLとして使用して解決されます。これらはそれ自体が参照元のドキュメントに対する相対的なものになる可能性があることに注意してください。

スキーマ

以下の説明では、フィールドが明示的に REQUIRED であるか、MUSTまたはSHALLで記述されていない場合、OPTIONALと見なすことができます。

OpenAPIオブジェクト

これは、OpenAPIドキュメントのルートオブジェクトです。

固定フィールド

フィールド名	型	説明
openapi	`文字列`	必須。この文字列は、OpenAPIドキュメントが使用するOpenAPI仕様のバージョン番号である必要があります。`openapi` フィールドは、OpenAPIドキュメントを解釈するためにツールによって使用される必要があります。これはAPIの`info.version`文字列とは関係ありません。
info	情報オブジェクト	必須。APIに関するメタデータを提供します。メタデータは、必要に応じてツールによって使用される場合があります。
jsonSchemaDialect	`文字列`	このOASドキュメントに含まれるスキーマオブジェクト内の `$schema` キーワードのデフォルト値。これはURI形式である必要があります。
servers	[サーバーオブジェクト]	ターゲットサーバーへの接続情報を提供するサーバーオブジェクトの配列。`servers`プロパティが指定されていないか、空の配列である場合、デフォルト値は、url値が `/` のサーバーオブジェクトになります。
paths	パスオブジェクト	APIで使用可能なパスと操作。
webhooks	Map[`string`, Path Item Object \| Reference Object] ]	このAPIの一部として受信される可能性があり、APIコンシューマーが実装を選択できる受信Webhooks。`callbacks`機能と密接に関連しており、このセクションでは、API呼び出し以外の方法で開始されるリクエスト（たとえば、アウトオブバンド登録によるリクエスト）について説明します。キー名は各Webhookを参照する一意の文字列であり、(オプションで参照される) Path Item Objectは、APIプロバイダーによって開始される可能性のあるリクエストと、予期されるレスポンスを記述します。例があります。
components	コンポーネントオブジェクト	ドキュメントのさまざまなスキーマを保持する要素。
security	[セキュリティ要件オブジェクト]	API全体で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のセキュリティ要件オブジェクトが含まれています。リクエストを承認するには、セキュリティ要件オブジェクトの1つだけを満たす必要があります。個々の操作はこの定義を上書きできます。セキュリティをオプションにするには、空のセキュリティ要件(`{}`)を配列に含めることができます。
tags	[タグオブジェクト]	追加のメタデータを含むドキュメントで使用されるタグのリスト。タグの順序は、解析ツールによる順序を反映するために使用できます。操作オブジェクトで使用されるすべてのタグを宣言する必要はありません。宣言されていないタグは、ツールロジックに基づいてランダムに、またはツールロジックに基づいて整理できます。リスト内の各タグ名は一意である必要があります。
externalDocs	外部ドキュメントオブジェクト	追加の外部ドキュメント。

このオブジェクトは、仕様拡張で拡張できます。

情報オブジェクト

このオブジェクトは、APIに関するメタデータを提供します。メタデータは必要に応じてクライアントで使用される場合があり、編集ツールまたはドキュメント生成ツールで利便性のために表示される場合があります。

固定フィールド

フィールド名	型	説明
title	`文字列`	必須。APIのタイトル。
summary	`文字列`	APIの短い要約。
description	`文字列`	APIの説明。CommonMark構文を使用して、リッチテキスト表現に使用できます。
termsOfService	`文字列`	APIの利用規約へのURL。これはURL形式である必要があります。
contact	連絡先オブジェクト	公開されているAPIの連絡先情報。
license	ライセンスオブジェクト	公開されているAPIのライセンス情報。
version	`文字列`	必須。OpenAPIドキュメントのバージョン（OpenAPI仕様バージョンまたはAPI実装バージョンとは異なります）。

このオブジェクトは、仕様拡張で拡張できます。

情報オブジェクトの例

{
  "title": "Sample Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://apache.dokyumento.jp/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Sample Pet Store App
summary: A pet store manager.
description: This is a sample server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/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	`文字列`	連絡担当者/組織のメールアドレス。これはメールアドレス形式である必要があります。

このオブジェクトは、仕様拡張で拡張できます。

連絡先オブジェクトの例

{
  "name": "API Support",
  "url": "https://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: https://www.example.com/support
email: [email protected]

ライセンスオブジェクト

公開されているAPIのライセンス情報。

固定フィールド

フィールド名	型	説明
name	`文字列`	必須。APIに使用されるライセンス名。
identifier	`文字列`	APIのSPDXライセンス式。`identifier`フィールドは、`url`フィールドと相互に排他的です。
url	`文字列`	APIに使用されるライセンスへのURL。これはURL形式である必要があります。`url`フィールドは、`identifier`フィールドと相互に排他的です。

このオブジェクトは、仕様拡張で拡張できます。

ライセンスオブジェクトの例

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

サーバーオブジェクト

サーバーを表すオブジェクト。

固定フィールド

フィールド名	型	説明
url	`文字列`	必須。ターゲットホストへのURL。このURLはサーバー変数をサポートし、OpenAPIドキュメントが提供されている場所に対してホストの場所が相対的であることを示すために相対的な場合があります。変数が `{` 中括弧 `}` で指定されている場合、変数の置換が行われます。
description	`文字列`	URLによって指定されたホストを説明するオプションの文字列。CommonMark構文を使用して、リッチテキスト表現に使用できます。
variables	Map[`string`, サーバー変数オブジェクト]	変数名とその値の間のマッピング。この値は、サーバーのURLテンプレートでの置換に使用されます。

このオブジェクトは、仕様拡張で拡張できます。

サーバーオブジェクトの例

単一のサーバーは次のように記述されます

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

以下は、たとえば、OpenAPIオブジェクトのserversで、複数のサーバーを記述する方法を示しています。

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

以下は、サーバー構成に変数を使用する方法を示しています。

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2

サーバー変数オブジェクト

サーバーURLテンプレートの置換に使用するサーバー変数を表すオブジェクト。

固定フィールド

フィールド名	型	説明
enum	[`string`]	置換オプションが限られたセットからのものである場合に使用される文字列値の列挙。配列は空であってはなりません。
default	`文字列`	必須。代替値が提供されていない場合に送信される、置換に使用するデフォルト値。この動作は、スキーマオブジェクトのデフォルト値の扱いとは異なります。これらの場合、パラメーター値はオプションであるためです。`enum` が定義されている場合、値はenumの値に存在する必要があります。
description	`文字列`	サーバー変数のオプションの説明。CommonMark構文を使用して、リッチテキスト表現に使用できます。

このオブジェクトは、仕様拡張で拡張できます。

コンポーネントオブジェクト

OASのさまざまな側面で使用できるオブジェクトのセットを保持します。componentsオブジェクト内で定義されたすべてのオブジェクトは、componentsオブジェクトの外側のプロパティから明示的に参照されない限り、APIに影響を与えません。

固定フィールド

フィールド名	型	説明
schemas	Map[`string`, スキーマオブジェクト]	再利用可能なスキーマオブジェクトを保持するオブジェクト。
responses	Map[`string`, レスポンスオブジェクト \| 参照オブジェクト]	再利用可能なレスポンスオブジェクトを保持するオブジェクト。
parameters	Map[`string`, パラメーターオブジェクト \| 参照オブジェクト]	再利用可能なパラメーターオブジェクトを保持するオブジェクト。
examples	Map[`string`, 例オブジェクト \| 参照オブジェクト]	再利用可能な例オブジェクトを保持するオブジェクト。
requestBodies	Map[`string`, リクエストボディオブジェクト \| 参照オブジェクト]	再利用可能なリクエストボディオブジェクトを保持するオブジェクト。
headers	Map[`string`, ヘッダーオブジェクト \| 参照オブジェクト]	再利用可能なヘッダーオブジェクトを保持するオブジェクト。
securitySchemes	Map[`string`, セキュリティスキームオブジェクト \| 参照オブジェクト]	再利用可能なセキュリティスキームオブジェクトを保持するオブジェクト。
links	Map[`string`, リンクオブジェクト \| 参照オブジェクト]	再利用可能なリンクオブジェクトを保持するオブジェクト。
callbacks	Map[`string`, コールバックオブジェクト \| 参照オブジェクト]	再利用可能なコールバックオブジェクトを保持するオブジェクト。
pathItems	Map[`string`, パスアイテムオブジェクト \| 参照オブジェクト]	再利用可能なパスアイテムオブジェクトを保持するオブジェクト。

このオブジェクトは、仕様拡張で拡張できます。

上記で宣言されたすべての固定フィールドは、正規表現：^[a-zA-Z0-9\.\-_]+$に一致するキーを使用する必要があるオブジェクトです。

フィールド名の例

User
User_1
User_Name
user-name
my.org.User

コンポーネントオブジェクトの例

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "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"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          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
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

パスオブジェクト

個々のエンドポイントとその操作への相対パスを保持します。パスは、完全なURLを構築するために、Server ObjectのURLに追加されます。パスは、アクセス制御リスト（ACL）の制約により、空になる場合があります。

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

フィールドパターン	型	説明
/{path}	パスアイテムオブジェクト	個々のエンドポイントへの相対パス。フィールド名は、スラッシュ（`/`）で始める必要があります。パスは、完全なURLを構築するために、`Server Object`の`url`フィールドから展開されたURLに追加されます（相対URL解決は行われません）。パステンプレートが許可されます。URLをマッチングする際、具象（テンプレート化されていない）パスは、テンプレート化された対応物よりも先にマッチングされます。同じ階層構造を持ち、異なるテンプレート名を持つテンプレート化されたパスは、同一であるため、存在してはなりません。あいまいなマッチングの場合、ツールがどちらを使用するかを決定します。

このオブジェクトは、仕様拡張で拡張できます。

パステンプレートのマッチング

以下のパスを仮定すると、具象定義である/pets/mineが最初に使用された場合にマッチングされます。

  /pets/{petId}
  /pets/mine

以下のパスは同一とみなされ、無効です。

  /pets/{petId}
  /pets/{name}

以下は、あいまいな解決につながる可能性があります。

  /{entity}/me
  /books/{id}

Pathsオブジェクトの例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {         
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

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

パスアイテムオブジェクト

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

固定フィールド

フィールド名	型	説明
$ref	`文字列`	このパス項目の参照定義を許可します。参照される構造は、パス項目オブジェクトの形式でなければなりません。パス項目オブジェクトのフィールドが、定義されたオブジェクトと参照されたオブジェクトの両方に現れる場合、動作は未定義です。URIの相対参照を解決するためのルールを参照してください。
summary	`文字列`	このパスのすべての操作に適用することを意図した、オプションの文字列サマリー。
description	`文字列`	このパスのすべての操作に適用することを意図した、オプションの文字列記述。CommonMark構文は、リッチテキスト表現に使用できます。
get	操作オブジェクト	このパスのGET操作の定義。
put	操作オブジェクト	このパスのPUT操作の定義。
post	操作オブジェクト	このパスのPOST操作の定義。
delete	操作オブジェクト	このパスのDELETE操作の定義。
options	操作オブジェクト	このパスのOPTIONS操作の定義。
head	操作オブジェクト	このパスのHEAD操作の定義。
patch	操作オブジェクト	このパスのPATCH操作の定義。
trace	操作オブジェクト	このパスのTRACE操作の定義。
servers	[サーバーオブジェクト]	このパスのすべての操作を処理するための代替の`server`配列。
parameters	[パラメータオブジェクト \| 参照オブジェクト]	このパスで記述されたすべての操作に適用可能なパラメータのリスト。これらのパラメータは操作レベルで上書きできますが、削除することはできません。リストには重複したパラメータを含めてはなりません。一意のパラメータは、nameとlocationの組み合わせによって定義されます。リストでは、参照オブジェクトを使用して、OpenAPIオブジェクトのcomponents/parametersで定義されているパラメータにリンクできます。

このオブジェクトは、仕様拡張で拡張できます。

パス項目オブジェクトの例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string 
  style: simple

操作オブジェクト

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

固定フィールド

フィールド名	型	説明
tags	[`string`]	APIドキュメント制御のためのタグのリスト。タグは、リソースまたはその他の修飾子による操作の論理的なグループ化に使用できます。
summary	`文字列`	操作の概要。
description	`文字列`	操作の動作の詳細な説明。CommonMark構文は、リッチテキスト表現に使用できます。
externalDocs	外部ドキュメントオブジェクト	この操作の追加の外部ドキュメント。
operationId	`文字列`	操作を識別するために使用される一意の文字列。IDは、APIで記述されているすべての操作間で一意である必要があります。operationIdの値は大文字と小文字を区別します。ツールやライブラリは、operationIdを使用して操作を一意に識別する可能性があるため、一般的なプログラミング命名規則に従うことをお勧めします。
parameters	[パラメータオブジェクト \| 参照オブジェクト]	この操作に適用可能なパラメータのリスト。パス項目ですでにパラメータが定義されている場合、新しい定義はそれを上書きしますが、削除することはできません。リストには重複したパラメータを含めてはなりません。一意のパラメータは、nameとlocationの組み合わせによって定義されます。リストでは、参照オブジェクトを使用して、OpenAPIオブジェクトのcomponents/parametersで定義されているパラメータにリンクできます。
requestBody	リクエストボディオブジェクト \| 参照オブジェクト	この操作に適用可能なリクエストボディ。`requestBody`は、HTTP 1.1仕様RFC7231でリクエストボディのセマンティクスが明示的に定義されているHTTPメソッドで完全にサポートされています。HTTP仕様があいまいな場合（GET、HEAD、DELETEなど）、`requestBody`は許可されていますが、明確なセマンティクスがなく、可能な限り避ける必要があります。
responses	レスポンスオブジェクト	この操作の実行から返される可能性のある応答のリスト。
callbacks	Map[`string`, コールバックオブジェクト \| 参照オブジェクト]	親操作に関連する可能性のある帯域外コールバックのマップ。キーは、コールバックオブジェクトの一意の識別子です。マップ内の各値は、APIプロバイダーによって開始される可能性のあるリクエストと、予期される応答を記述したコールバックオブジェクトです。
deprecated	`boolean`	この操作が非推奨であることを宣言します。コンシューマーは、宣言された操作の使用を控える必要があります。デフォルト値は`false`です。
security	[セキュリティ要件オブジェクト]	この操作に使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替セキュリティ要件オブジェクトが含まれます。リクエストを承認するには、セキュリティ要件オブジェクトの1つだけを満たす必要があります。セキュリティをオプションにするには、空のセキュリティ要件（`{}`）を配列に含めることができます。この定義は、宣言されたトップレベルの`security`を上書きします。トップレベルのセキュリティ宣言を削除するには、空の配列を使用できます。
servers	[サーバーオブジェクト]	この操作を処理するための代替の`server`配列。代替の`server`オブジェクトがパス項目オブジェクトまたはルートレベルで指定されている場合、この値によって上書きされます。

このオブジェクトは、仕様拡張で拡張できます。

操作オブジェクトの例

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       type: object
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

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

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

固定フィールド

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

このオブジェクトは、仕様拡張で拡張できます。

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

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

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

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

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

パラメータの場所

inフィールドで指定される、4つの可能なパラメータの場所があります。

path - パステンプレートとともに使用され、パラメータ値は実際には操作のURLの一部です。これには、APIのホストまたはベースパスは含まれません。たとえば、/items/{itemId}では、パスパラメータはitemIdです。
query - URLに追加されるパラメータ。たとえば、/items?id=###では、クエリパラメータはidです。
header - リクエストの一部として期待されるカスタムヘッダー。RFC7230では、ヘッダー名は大文字と小文字を区別しないことに注意してください。
cookie - 特定のCookie値をAPIに渡すために使用されます。

固定フィールド

フィールド名	型	説明
name	`文字列`	必須。パラメータの名前。パラメータ名は大文字と小文字を区別します。 `in`が`"path"`の場合、`name`フィールドは、Paths Objectのpathフィールド内で発生するテンプレート式に対応している必要があります。詳細については、パステンプレートを参照してください。 `in`が`"header"`で、`name`フィールドが`"Accept"`、`"Content-Type"`、または`"Authorization"`の場合、パラメータ定義は無視されます。他のすべての場合、`name`は、`in`プロパティで使用されるパラメータ名に対応します。
in	`文字列`	必須。パラメータの場所。可能な値は、`"query"`、`"header"`、`"path"`、または`"cookie"`です。
description	`文字列`	パラメータの簡単な説明。これには、使用例を含めることができます。CommonMark構文は、リッチテキスト表現に使用できます。
required	`boolean`	このパラメータが必須かどうかを決定します。パラメータの場所が`"path"`の場合、このプロパティは必須であり、その値は`true`である必要があります。それ以外の場合、プロパティを含めることができ、そのデフォルト値は`false`です。
deprecated	`boolean`	パラメータが非推奨であり、使用をやめるべきであることを指定します。デフォルト値は`false`です。
allowEmptyValue	`boolean`	空の値のパラメータを渡す機能を設定します。これは`query`パラメータでのみ有効であり、空の値を持つパラメータの送信を許可します。デフォルト値は`false`です。`style`が使用されている場合、動作が`n/a`（シリアル化できない）の場合、`allowEmptyValue`の値は無視されます。このプロパティの使用は推奨されません。後の改訂で削除される可能性があります。

パラメータのシリアル化のルールは、2つの方法のいずれかで指定されます。より単純なシナリオでは、schemaとstyleが、パラメータの構造と構文を記述できます。

フィールド名	型	説明
style	`文字列`	パラメータ値の型に応じて、パラメータ値がどのようにシリアル化されるかを記述します。デフォルト値（`in`の値に基づく）：`query`の場合は`form`、`path`の場合は`simple`、`header`の場合は`simple`、`cookie`の場合は`form`です。
explode	`boolean`	これが真の場合、`array`型または`object`型のパラメーター値は、配列の各値またはマップのキーと値のペアごとに個別のパラメーターを生成します。他の型のパラメーターの場合、このプロパティは効果がありません。`style`が`form`の場合、デフォルト値は`true`です。他のすべてのスタイルでは、デフォルト値は`false`です。
allowReserved	`boolean`	パラメーター値が、RFC3986で定義されている予約文字`:/?#[]@!$&'()*+,;=`をパーセントエンコーディングなしで含めることを許可すべきかどうかを決定します。このプロパティは、`in`の値が`query`のパラメーターにのみ適用されます。デフォルト値は`false`です。
schema	スキーマオブジェクト	パラメーターに使用される型を定義するスキーマ。
example	任意	パラメーターの潜在的な値の例。この例は、指定されたスキーマおよびエンコーディングプロパティ（存在する場合）と一致する必要があります。`example`フィールドは、`examples`フィールドと相互に排他的です。さらに、例を含む`schema`を参照する場合、`example`の値は、スキーマによって提供される例をオーバーライドする必要があります。JSONまたはYAMLで自然に表現できないメディアタイプの例を表すには、文字列値に、必要に応じてエスケープされた例を含めることができます。
examples	マップ[`string`, Example Object \| Reference Object]	パラメーターの潜在的な値の例。各例には、パラメーターエンコーディングで指定されている正しい形式の値が含まれている必要があります。`examples`フィールドは、`example`フィールドと相互に排他的です。さらに、例を含む`schema`を参照する場合、`examples`の値は、スキーマによって提供される例をオーバーライドする必要があります。

より複雑なシナリオでは、contentプロパティがパラメーターのメディアタイプとスキーマを定義できます。パラメーターには、schemaプロパティまたはcontentプロパティのいずれかを含める必要がありますが、両方を含めることはできません。exampleまたはexamplesがschemaオブジェクトと組み合わせて提供される場合、例はパラメーターの規定されたシリアル化戦略に従う必要があります。

フィールド名	型	説明
content	マップ[`string`, Media Type Object]	パラメーターの表現を含むマップ。キーはメディアタイプであり、値はそれを記述します。マップにはエントリが1つだけ含まれている必要があります。

スタイル値

単純なパラメーターをシリアル化する一般的な方法をサポートするために、一連のstyle値が定義されています。

`style`	`タイプ`	`in`	コメント
matrix	`primitive`、`array`、`object`	`path`	RFC6570で定義されているパススタイルのパラメーター
label	`primitive`、`array`、`object`	`path`	RFC6570で定義されているラベルスタイルのパラメーター
form	`primitive`、`array`、`object`	`query`、`cookie`	RFC6570で定義されているフォームスタイルのパラメーター。このオプションは、OpenAPI 2.0の`collectionFormat`を`csv`（`explode`がfalseの場合）または`multi`（`explode`がtrueの場合）の値に置き換えます。
simple	`array`	`path`、`header`	RFC6570で定義されているシンプルスタイルのパラメーター。このオプションは、OpenAPI 2.0の`collectionFormat`を`csv`の値に置き換えます。
spaceDelimited	`array`、`object`	`query`	スペースで区切られた配列またはオブジェクトの値。このオプションは、OpenAPI 2.0の`collectionFormat`が`ssv`に等しい場合に置き換えます。
pipeDelimited	`array`、`object`	`query`	パイプで区切られた配列またはオブジェクトの値。このオプションは、OpenAPI 2.0の`collectionFormat`が`pipes`に等しい場合に置き換えます。
deepObject	`object`	`query`	フォームパラメーターを使用してネストされたオブジェクトをレンダリングする簡単な方法を提供します。

スタイルの例

colorという名前のパラメーターに、次のいずれかの値があることを想定します

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

次の表は、各値に対するレンダリングの違いの例を示しています。

`style`	`explode`	`empty`	`文字列`	`array`	`object`
matrix	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
matrix	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
label	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
label	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
form	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
form	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
simple	false	n/a	blue	blue,black,brown	R,100,G,200,B,150
simple	true	n/a	blue	blue,black,brown	R=100,G=200,B=150
spaceDelimited	false	n/a	n/a	blue%20black%20brown	R%20100%20G%20200%20B%20150
pipeDelimited	false	n/a	n/a	blue\|black\|brown	R\|100\|G\|200\|B\|150
deepObject	true	n/a	n/a	n/a	color[R]=100&color[G]=200&color[B]=150

このオブジェクトは、仕様拡張で拡張できます。

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

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

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

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

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

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

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

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

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

特定の型の未定義パラメーターを許可する、自由形式のクエリパラメーター

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    },
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

シリアル化を定義するためにcontentを使用する複合パラメーター

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

リクエストボディオブジェクト

単一のリクエストボディを記述します。

固定フィールド

フィールド名	型	説明
description	`文字列`	リクエストボディの簡単な説明。これには使用例が含まれる場合があります。CommonMark構文は、リッチテキスト表現に使用できます。
content	マップ[`string`, Media Type Object]	必須。リクエストボディの内容。キーはメディアタイプまたはメディアタイプの範囲であり、値はそれを記述します。複数のキーに一致するリクエストの場合、最も具体的なキーのみが適用されます。例：text/plainはtext/*をオーバーライドします。
required	`boolean`	リクエストでリクエストボディが必要かどうかを決定します。デフォルトは`false`です。

このオブジェクトは、仕様拡張で拡張できます。

リクエストボディの例

参照されるモデル定義を含むリクエストボディ。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example",
            "externalValue": "https://foo.bar/examples/user-example.json"
          }
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "https://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "https://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'https://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: 'https://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: User example in Plain text
        externalValue: 'https://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: 'https://foo.bar/examples/user-example.whatever'

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

{
  "description": "user to add to the system",
  "required": true,
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

description: user to add to the system
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

メディアタイプオブジェクト

各メディアタイプオブジェクトは、キーによって識別されるメディアタイプのスキーマと例を提供します。

固定フィールド

フィールド名	型	説明
schema	スキーマオブジェクト	リクエスト、レスポンス、またはパラメーターのコンテンツを定義するスキーマ。
example	任意	メディアタイプの例。例オブジェクトは、メディアタイプで指定されている正しい形式である必要があります。`example`フィールドは、`examples`フィールドと相互に排他的です。さらに、例を含む`schema`を参照する場合、`example`の値は、スキーマによって提供される例をオーバーライドする必要があります。
examples	マップ[`string`, Example Object \| Reference Object]	メディアタイプの例。各例オブジェクトは、メディアタイプと、指定されている場合は指定されたスキーマと一致する必要があります。`examples`フィールドは、`example`フィールドと相互に排他的です。さらに、例を含む`schema`を参照する場合、`examples`の値は、スキーマによって提供される例をオーバーライドする必要があります。
encoding	マップ[`string`, Encoding Object]	プロパティ名とそのエンコーディング情報の間のマップ。キーであるプロパティ名は、スキーマ内にプロパティとして存在する必要があります。エンコーディングオブジェクトは、メディアタイプが`multipart`または`application/x-www-form-urlencoded`の場合にのみ、`requestBody`オブジェクトに適用されます。

このオブジェクトは、仕様拡張で拡張できます。

メディアタイプの例

{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

ファイルアップロードに関する考慮事項

2.0仕様とは対照的に、OpenAPIのfile入力/出力コンテンツは、他のスキーマタイプと同じセマンティクスで記述されます。

3.0仕様とは対照的に、formatキーワードはスキーマのコンテンツエンコーディングには影響しません。JSONスキーマは、スキーマのContent-Encodingを指定するために使用できるcontentEncodingキーワードを提供します。contentEncodingキーワードは、RFC4648で定義されているすべてのエンコーディング（「base64」や「base64url」など）、およびRFC2045の「quoted-printable」をサポートします。contentEncodingキーワードで指定されたエンコーディングは、リクエストまたはレスポンスのContent-Typeヘッダーまたはマルチパートボディのメタデータで指定されたエンコーディングとは独立しています。両方が存在する場合、contentEncodingで指定されたエンコーディングが最初に適用され、次にContent-Typeヘッダーで指定されたエンコーディングが適用されます。

JSONスキーマは、contentMediaTypeキーワードも提供します。ただし、メディアタイプが既にメディアタイプオブジェクトのキー、またはエンコーディングオブジェクトのcontentTypeフィールドで指定されている場合、contentMediaTypeキーワードが存在する場合は無視されます。

例

バイナリ（オクテットストリーム）で転送されるコンテンツは、schemaを省略できます

# a PNG image as a binary file:
content:
    image/png: {}

# an arbitrary binary file:
content:
    application/octet-stream: {}

base64エンコーディングで転送されるバイナリコンテンツ

content:
    image/png:
        schema:
            type: string
            contentMediaType: image/png
            contentEncoding: base64

Content-Typeはimage/pngのままであり、ペイロードのセマンティクスを記述していることに注意してください。JSONスキーマのtypeおよびcontentEncodingフィールドは、ペイロードがテキストとして転送されることを説明しています。JSONスキーマのcontentMediaTypeは技術的には冗長ですが、OpenAPIコンテキストを認識していない可能性のあるJSONスキーマツールで使用できます。

これらの例は、ファイルアップロードの入力ペイロードまたはレスポンスペイロードのいずれかに適用されます。

POST操作でファイルを送信するためのrequestBodyは、次の例のようになります

requestBody:
  content:
    application/octet-stream: {}

さらに、特定のメディアタイプを指定できます

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

複数のファイルをアップロードするには、multipartメディアタイプを使用する必要があります

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items: {}

以下のmultipart/form-dataのセクションでわかるように、itemsの空のスキーマは、application/octet-streamのメディアタイプを示しています。

x-www-form-urlencodedリクエストボディのサポート

RFC1866を介してフォームURLエンコーディングを使用してコンテンツを送信するには、次の定義を使用できます

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

この例では、requestBodyのコンテンツは、サーバーに渡されるときにRFC1866に従って文字列化する必要があります。さらに、addressフィールドの複合オブジェクトは文字列化されます。

application/x-www-form-urlencodedコンテンツタイプで複合オブジェクトを渡す場合、そのようなプロパティのデフォルトのシリアル化戦略は、Encoding Objectのstyleプロパティとしてformで記述されています。

`multipart`コンテンツに関する特別な考慮事項

操作にリクエストボディを転送するときに、multipart/form-dataをContent-Typeとして使用するのが一般的です。2.0とは対照的に、multipartコンテンツを使用する場合、操作への入力パラメーターを定義するにはschemaが必須です。これにより、複数のファイルアップロードのサポートメカニズムだけでなく、複雑な構造もサポートされます。

multipart/form-dataリクエストボディでは、各スキーマプロパティ、またはスキーマ配列プロパティの各要素は、RFC7578で定義されている内部ヘッダーを持つペイロード内のセクションを取得します。multipart/form-dataリクエストボディの各プロパティのシリアル化戦略は、関連するEncoding Objectで指定できます。

multipart 型を渡す場合、転送されるコンテンツのセクションを区切るために境界を使用できます。したがって、以下のデフォルトの Content-Type が multipart に対して定義されています。

プロパティがプリミティブ型、またはプリミティブ値の配列である場合、デフォルトの Content-Type は text/plain です。
プロパティが複合型、または複合値の配列である場合、デフォルトの Content-Type は application/json です。
プロパティが type: string であり、contentEncoding が指定されている場合、デフォルトの Content-Type は application/octet-stream です。

JSON Schema 仕様に従い、contentEncoding が存在しない場合の contentMediaType は、contentEncoding: identity が存在する場合と同様に扱われます。これは、text/html などのテキストドキュメントを JSON 文字列に埋め込むには便利ですが、multipart/form-data パートには、ドキュメントが実際のメディアタイプではなく text/plain として扱われるだけなので、役に立ちません。contentEncoding が不要な場合は、contentMediaType なしのエンコーディングオブジェクトを使用してください。

例

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {}
          profileImage:
            # Content-Type for application-level encoded resource is `text/plain`
            type: string
            contentMediaType: image/png
            contentEncoding: base64
          children:
            # default Content-Type for arrays is based on the _inner_ type (`text/plain` here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the _inner_ type (object shown, so `application/json` in this example)
            type: array
            items:
              type: object
              $ref: '#/components/schemas/Address'

multipart リクエストボディの一部をシリアライズする際に制御を可能にするために、encoding 属性が導入されました。この属性は multipart および application/x-www-form-urlencoded リクエストボディにのみ適用可能です。

エンコーディングオブジェクト

単一のスキーマプロパティに適用される単一のエンコーディング定義。

固定フィールド

フィールド名	型	説明
contentType	`文字列`	特定のプロパティをエンコードするための Content-Type。デフォルト値はプロパティの型によって異なります。`object` の場合は `application/json`、`array` の場合は内部の型に基づいて定義され、その他のすべての場合のデフォルトは `application/octet-stream` です。値は、特定のメディアタイプ（例：`application/json`）、ワイルドカードメディアタイプ（例：`image/*`）、または両方のタイプをコンマで区切ったリストにできます。
headers	Map[`string`, ヘッダーオブジェクト \| 参照オブジェクト]	追加情報をヘッダーとして提供できるマップ（例：`Content-Disposition`）。`Content-Type` は別途記述されており、このセクションでは無視される必要があります。このプロパティは、リクエストボディのメディアタイプが `multipart` でない場合は無視される必要があります。
style	`文字列`	特定のプロパティ値がその型に応じてどのようにシリアライズされるかを記述します。詳細については、パラメータオブジェクトの `style` プロパティを参照してください。動作は、デフォルト値を含め、`query` パラメータと同じ値を持ちます。このプロパティは、リクエストボディのメディアタイプが `application/x-www-form-urlencoded` または `multipart/form-data` でない場合は無視される必要があります。値が明示的に定義されている場合、`contentType` (暗黙的または明示的) の値は無視される必要があります。
explode	`boolean`	これが true の場合、`array` または `object` 型のプロパティ値は、配列の各値、またはマップのキーと値のペアごとに個別のパラメータを生成します。他の型のプロパティの場合、このプロパティは効果がありません。`style` が `form` の場合、デフォルト値は `true` です。他のすべてのスタイルの場合、デフォルト値は `false` です。このプロパティは、リクエストボディのメディアタイプが `application/x-www-form-urlencoded` または `multipart/form-data` でない場合は無視される必要があります。値が明示的に定義されている場合、`contentType` (暗黙的または明示的) の値は無視される必要があります。
allowReserved	`boolean`	RFC3986 で定義されている予約文字 `:/?#[]@!$&'()*+,;=` をパーセントエンコードせずに含めることをパラメータ値で許可する必要があるかどうかを決定します。デフォルト値は `false` です。このプロパティは、リクエストボディのメディアタイプが `application/x-www-form-urlencoded` または `multipart/form-data` でない場合は無視される必要があります。値が明示的に定義されている場合、`contentType` (暗黙的または明示的) の値は無視される必要があります。

このオブジェクトは、仕様拡張で拡張できます。

エンコーディングオブジェクトの例

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage: {}
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

レスポンスオブジェクト

操作の予期される応答のコンテナ。コンテナは、HTTP 応答コードを予期される応答にマッピングします。

ドキュメントは、事前に不明な場合があるため、可能なすべての HTTP 応答コードを網羅する必要があるとは限りません。ただし、ドキュメントは、成功した操作の応答と、既知のエラーを網羅することが期待されます。

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

Responses Object は、少なくとも 1 つの応答コードを含める必要があり、1 つの応答コードのみが提供されている場合は、成功した操作呼び出しの応答である必要があります。

固定フィールド

フィールド名	型	説明
default	Response Object \| Reference Object	特定の HTTP 応答コードに対して宣言されたもの以外の応答のドキュメント。このフィールドを使用して、宣言されていない応答をカバーします。

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

フィールドパターン	型	説明
HTTPステータスコード	Response Object \| Reference Object	任意の HTTP ステータスコードをプロパティ名として使用できますが、HTTP ステータスコードごとに 1 つのプロパティのみを使用し、その HTTP ステータスコードに対する予期される応答を記述します。このフィールドは、JSON と YAML の互換性のために、引用符で囲む必要があります（例：「200」）。応答コードの範囲を定義するために、このフィールドには大文字のワイルドカード文字 `X` を含めることができます。たとえば、`2XX` は `[200-299]` の間のすべての応答コードを表します。許可される範囲の定義は、`1XX`、`2XX`、`3XX`、`4XX`、および `5XX` のみです。明示的なコードを使用して応答が定義されている場合、明示的なコード定義は、そのコードの範囲定義よりも優先されます。

このオブジェクトは、仕様拡張で拡張できます。

応答オブジェクトの例

成功した操作の 200 応答と、その他 (エラーを示唆する) のデフォルト応答

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

レスポンスオブジェクト

API 操作からの単一の応答を記述します。応答に基づく操作への設計時、静的な links を含みます。

固定フィールド

フィールド名	型	説明
description	`文字列`	必須。レスポンスの説明。CommonMark 構文を使用して、リッチテキスト表現を記述できます。
headers	Map[`string`, ヘッダーオブジェクト \| 参照オブジェクト]	ヘッダー名をその定義にマッピングします。RFC7230 は、ヘッダー名は大文字と小文字を区別しないと述べています。応答ヘッダーが `"Content-Type"` という名前で定義されている場合は、無視する必要があります。
content	マップ[`string`, Media Type Object]	可能性のあるレスポンスペイロードの説明を含むマップ。キーは、メディアタイプまたはメディアタイプ範囲であり、値はそれを記述します。複数のキーに一致する応答の場合、最も具体的なキーのみが適用されます。例：text/plain は text/* を上書きします。
links	Map[`string`, リンクオブジェクト \| 参照オブジェクト]	応答から追跡できる操作リンクのマップ。マップのキーは、コンポーネントオブジェクトの名前付け制約に従う、リンクの短い名前です。

このオブジェクトは、仕様拡張で拡張できます。

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

複合型の配列のレスポンス

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

文字列型のレスポンス

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }

}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

ヘッダー付きのプレーンテキストレスポンス

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

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

戻り値なしのレスポンス

{
  "description": "object created"
}

description: object created

コールバックオブジェクト

親操作に関連する可能性のある帯域外コールバックのマップ。マップ内の各値は、API プロバイダーによって開始される可能性のある一連のリクエストと、予期されるレスポンスを記述するパス項目オブジェクトです。パス項目オブジェクトを識別するために使用されるキー値は、コールバック操作に使用する URL を識別するために、ランタイムで評価される式です。

別の API 呼び出しとは独立した API プロバイダーからの着信リクエストを記述するには、webhooks フィールドを使用します。

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

フィールドパターン	型	説明
{expression}	パス項目オブジェクト \| 参照オブジェクト	コールバックリクエストと予期されるレスポンスを定義するために使用される、パス項目オブジェクト、またはパス項目オブジェクトへの参照。完全な例が利用可能です。

このオブジェクトは、仕様拡張で拡張できます。

キー式

パス項目オブジェクトを識別するキーは、ランタイムの HTTP リクエスト/レスポンスのコンテキストで評価して、コールバックリクエストに使用する URL を識別できるランタイム式です。簡単な例としては $request.body#/url があります。ただし、ランタイム式を使用すると、完全な HTTP メッセージにアクセスできます。これには、JSON ポインタ RFC6901 が参照できる本体の任意の部分へのアクセスが含まれます。

たとえば、次の HTTP リクエストがあるとします。

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "https://clientdomain.com/failed",
  "successUrls" : [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}

201 Created
Location: https://example.org/subscription/1

次の例は、コールバック操作に eventType という名前のパスパラメータと、queryUrl という名前のクエリパラメータがあると仮定して、さまざまな式がどのように評価されるかを示しています。

式	値
$url	https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	https://clientdomain.com/stillrunning
$request.header.content-Type	application/json
$request.body#/failedUrl	https://clientdomain.com/failed
$request.body#/successUrls/2	https://clientdomain.com/medium
$response.header.Location	https://example.org/subscription/1

コールバックオブジェクトの例

次の例では、ユーザーが指定した queryUrl クエリ文字列パラメータを使用して、コールバック URL を定義しています。これは、コールバックオブジェクトを使用して、WebHook への登録を有効にするサブスクリプション操作に伴う WebHook コールバックを記述する方法の例です。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

次の例は、サーバーがハードコードされているが、クエリ文字列パラメータがリクエストボディの id プロパティと email プロパティから設定されるコールバックを示しています。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

サンプルオブジェクト

固定フィールド

フィールド名	型	説明
summary	`文字列`	例の簡単な説明。
description	`文字列`	例の長い説明。CommonMark 構文を使用して、リッチテキスト表現を記述できます。
value	任意	埋め込みリテラル例。`value` フィールドと `externalValue` フィールドは相互に排他的です。JSON または YAML で自然に表現できないメディアタイプの例を表すには、必要に応じてエスケープして例を含めるために文字列値を使用します。
externalValue	`文字列`	リテラルな例を指すURI。これにより、JSONドキュメントやYAMLドキュメントに簡単に含めることができない例を参照する機能を提供します。`value`フィールドと`externalValue`フィールドは相互に排他的です。相対参照の解決規則を参照してください。

このオブジェクトは、仕様拡張で拡張できます。

すべての場合において、例の値は、関連付けられた値の型スキーマと互換性があることが期待されます。ツール実装は、互換性を自動的に検証し、互換性がない場合は例の値を拒否することができます（MAY）。

Example オブジェクトの例

リクエストボディ内

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'https://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'https://foo.bar/examples/address-example.txt'

パラメーター内

parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'

レスポンス内

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

リンクオブジェクト

Link objectは、レスポンスに対する可能な設計時のリンクを表します。リンクの存在は、呼び出し側が正常にそれを呼び出す能力を保証するものではなく、レスポンスと他の操作間の既知の関係とトラバーサルメカニズムを提供します。

動的リンク（つまり、レスポンスペイロード内で提供されるリンク）とは異なり、OASリンクメカニズムは、ランタイムレスポンスでリンク情報を必要としません。

リンクを計算し、それらを実行するための指示を提供するために、ランタイム式は、操作の値にアクセスし、リンクされた操作を呼び出す際にそれらをパラメーターとして使用するために使用されます。

固定フィールド

フィールド名	型	説明
operationRef	`文字列`	OAS操作への相対または絶対URI参照。このフィールドは`operationId`フィールドと相互に排他的であり、Operation Objectを指す必要があります。相対`operationRef`値は、OpenAPI定義内の既存のOperation Objectを見つけるために使用できます。相対参照の解決規則を参照してください。
operationId	`文字列`	一意の`operationId`で定義された、既存の解決可能なOAS操作の名前。このフィールドは`operationRef`フィールドと相互に排他的です。
parameters	Map[`string`, Any \| {expression}]	`operationId`で指定された、または`operationRef`を介して識別された操作に渡すパラメーターを表すマップ。キーは使用するパラメーター名であり、値は定数または評価されてリンクされた操作に渡される式にすることができます。パラメーター名は、異なる場所で同じパラメーター名を使用する操作のために、パラメーターの場所`[{in}.]{name}`を使用して修飾できます（例：path.id）。
requestBody	Any \| {expression}	ターゲット操作を呼び出すときにリクエストボディとして使用するリテラル値または{expression}。
description	`文字列`	リンクの説明。CommonMark構文をリッチテキスト表現に使用できます（MAY）。
server	サーバーオブジェクト	ターゲット操作で使用されるサーバーオブジェクト。

このオブジェクトは、仕様拡張で拡張できます。

リンクされた操作は、operationRefまたはoperationIdのいずれかを使用して識別する必要があります。operationIdの場合、OASドキュメントのスコープ内で一意であり、解決される必要があります。名前の衝突の可能性があるため、operationRef構文は外部参照を持つOpenAPIドキュメントで推奨されます。

例

$request.path.idがリンクされた操作にリクエストパラメーターを渡すために使用されるリクエスト操作からリンクを計算します。

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

ランタイム式の評価に失敗した場合、ターゲット操作にパラメーター値は渡されません。

レスポンスボディの値を使用して、リンクされた操作を駆動できます。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

クライアントは、独自の判断で、すべてのリンクに従います。関係の存在のみによって、アクセス許可も、そのリンクへの正常な呼び出しを行う機能も保証されません。

OperationRefの例

operationIdへの参照は不可能である可能性があるので（operationIdはOperation Objectのオプションフィールドです）、相対operationRefを介して参照することもできます（MAY）。

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

または絶対operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

operationRefの使用では、JSON参照を使用する場合、エスケープされたスラッシュが必要であることに注意してください。

ランタイム式

ランタイム式を使用すると、実際のAPI呼び出しでHTTPメッセージ内でのみ利用可能になる情報に基づいて値を定義できます。このメカニズムは、Link ObjectおよびCallback Objectで使用されます。

ランタイム式は、次のABNF構文で定義されます。

      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
      source = ( header-reference / query-reference / path-reference / body-reference )
      header-reference = "header." token
      query-reference = "query." name 
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      json-pointer    = *( "/" reference-token )
      reference-token = *( unescaped / escaped )
      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
      escaped         = "~" ( "0" / "1" )
        ; representing '~' and '/', respectively
      name = *( CHAR )
      token = 1*tchar
      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

ここで、json-pointerはRFC6901、charはRFC7159、tokenはRFC7230から取得されます。

name識別子はケースセンシティブですが、tokenはケースセンシティブではありません。

以下の表に、ランタイム式の例と値での使用例を示します。

例

ソースの場所	式の例	備考
HTTPメソッド	`$method`	`$method`の許容値は、HTTP操作の値になります。
リクエストされたメディアタイプ	`$request.header.accept`
リクエストパラメーター	`$request.path.id`	リクエストパラメーターは、親操作の`parameters`セクションで宣言する必要があります。そうしないと、評価できません。これにはリクエストヘッダーが含まれます。
リクエストボディプロパティ	`$request.body#/user/uuid`	ペイロードを受け入れる操作では、`requestBody`の一部またはボディ全体を参照できます。
リクエストURL	`$url`
レスポンス値	`$response.body#/status`	ペイロードを返す操作では、レスポンスボディの一部またはボディ全体を参照できます。
レスポンスヘッダー	`$response.header.Server`	単一のヘッダー値のみが利用可能です

ランタイム式は、参照された値の型を保持します。式を{}波かっこで囲むことで、文字列値に埋め込むことができます。

ヘッダーオブジェクト

Header Objectは、次の変更を加えて、Parameter Objectの構造に従います。

nameは指定しないでください（MUST NOT）。対応するheadersマップで指定されます。
inは指定しないでください（MUST NOT）。暗黙的にheader内になります。
場所によって影響を受けるすべての特性は、headerの場所に適用可能である必要があります（たとえば、style）。

Header Objectの例

integer型の単純なヘッダー

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

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

タグオブジェクト

Operation Objectで使用される単一のタグにメタデータを追加します。Operation Objectインスタンスで定義されたタグごとにTag Objectを持つことは必須ではありません。

固定フィールド

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

このオブジェクトは、仕様拡張で拡張できます。

Tag Objectの例

{
	"name": "pet",
	"description": "Pets operations"
}

name: pet
description: Pets operations

参照オブジェクト

OpenAPIドキュメント内の他のコンポーネントを内部および外部で参照できるようにする単純なオブジェクト。

$ref文字列値には、参照されている値の場所を識別するURI RFC3986が含まれています。

相対参照の解決規則を参照してください。

固定フィールド

フィールド名	型	説明
$ref	`文字列`	必須。参照識別子。これはURIの形式である必要があります（MUST）。
summary	`文字列`	デフォルトでは、参照されるコンポーネントのサマリーを上書きする短いサマリー。参照されるオブジェクト型が`summary`フィールドを許可しない場合、このフィールドは影響しません。
description	`文字列`	デフォルトでは、参照されるコンポーネントの説明を上書きする説明。CommonMark構文をリッチテキスト表現に使用できます（MAY）。参照されるオブジェクト型が`description`フィールドを許可しない場合、このフィールドは影響しません。

このオブジェクトは追加のプロパティで拡張できず、追加されたプロパティは無視されます（SHALL）。

追加のプロパティに関するこの制限は、Reference Objectと$refキーワードを含むSchema Objectの違いであることに注意してください。

Reference Objectの例

{
	"$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

相対スキーマドキュメントの例

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

埋め込みスキーマを使用した相対ドキュメントの例

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

スキーマオブジェクト

Schema Objectを使用すると、入力および出力データ型の定義が可能です。これらの型はオブジェクトである可能性もありますが、プリミティブおよび配列である可能性もあります。このオブジェクトは、JSON Schema Specification Draft 2020-12のスーパーセットです。

プロパティの詳細については、JSON Schema CoreおよびJSON Schema Validationを参照してください。

特に明記されていない限り、プロパティの定義はJSON Schemaの定義に従い、追加のセマンティクスは追加しません。JSON Schemaが動作をアプリケーション（例：注釈の場合）で定義することを指示する場合、OASもOpenAPIドキュメントを使用するアプリケーションへのセマンティクスの定義を延期します。

プロパティ

OpenAPI Schema Object 方言は、JSON Schemaドラフト2020-12 汎用メタスキーマで指定されている語彙に加えて、OASベース語彙を必要とするように定義されています。

この仕様のバージョンのOpenAPI Schema Objectの方言は、URI https://spec.openapis.org/oas/3.1/dialect/base（「OAS方言スキーマID」）で識別されます。

次のプロパティはJSON Schema仕様から取得されますが、それらの定義はOASによって拡張されています。

description - CommonMark構文をリッチテキスト表現に使用できます（MAY）。
format - 詳細については、Data Type Formatsを参照してください。JSON Schemaで定義された形式に依存しながら、OASはいくつかの追加の定義済み形式を提供します。

OAS方言を構成するJSON Schemaプロパティに加えて、Schema Objectは他の任意の語彙、または完全に任意のプロパティからのキーワードをサポートします。

OpenAPI Specificationのベース語彙は、次のキーワードで構成されています。

固定フィールド

フィールド名	型	説明
discriminator	判別子オブジェクト	ポリモーフィズムのサポートを追加します。識別子は、ペイロードの説明を満たす可能性のある他のスキーマを区別するために使用されるオブジェクト名です。詳細については、Composition and Inheritanceを参照してください。
xml	XMLオブジェクト	これは、プロパティスキーマでのみ使用できます（MAY）。ルートスキーマには影響しません。このプロパティのXML表現を記述するための追加のメタデータを追加します。
externalDocs	外部ドキュメントオブジェクト	このスキーマの追加の外部ドキュメント。
example	任意	このスキーマのインスタンスの例を含めるための自由形式のプロパティ。JSONまたはYAMLで自然に表現できない例を表すために、必要な場合にエスケープを使用して例を含むために文字列値を使用できます。非推奨：`example`プロパティは、JSON Schemaの`examples`キーワードを支持して非推奨になりました。`example`の使用は推奨されておらず、この仕様の後のバージョンでは削除される可能性があります。

このオブジェクトは、Specification Extensionsで拡張できますが、前述のように、追加のプロパティはこのオブジェクト内でx-プレフィックスを省略できます。

構成と継承（ポリモーフィズム）

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

コンポジションはモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。ポリモーフィズムをサポートするために、OpenAPI Specificationではdiscriminatorフィールドが追加されています。使用する場合、discriminatorはモデルの構造を検証するスキーマ定義を決定するプロパティの名前になります。そのため、discriminatorフィールドは必須フィールドでなければなりません。継承インスタンスのdiscriminatorの値を定義するには、2つの方法があります。

スキーマ名を使用する。
プロパティを新しい値でオーバーライドすることにより、スキーマ名をオーバーライドします。新しい値が存在する場合、これはスキーマ名よりも優先されます。そのため、IDが指定されていないインラインスキーマ定義は、ポリモーフィズムでは使用できません。

XMLモデリング

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

スキーマ方言の指定

ツールが、特定のリソースをどのダイアレクトまたはメタスキーマで処理する必要があるかを判断できるようにすることが重要です。JSON Schema Core、JSON Schema Validation、OpenAPI Schemaダイアレクト、またはいくつかのカスタムメタスキーマなどです。

$schemaキーワードは、任意のルートスキーマオブジェクトに存在してもよく、存在する場合は、スキーマの処理に使用するダイアレクトを決定するために使用する必要があります。これにより、デフォルトのDraft 2020-12サポート以外のJSONスキーマの他のドラフトに準拠するスキーマオブジェクトを使用できます。ツールは、OASダイアレクトスキーマIDをサポートする必要があり、$schemaの追加値をサポートしてもかまいません。

OASドキュメントに含まれるすべてのスキーマオブジェクトに対して、別のデフォルトの$schema値を使用できるようにするには、OpenAPIオブジェクト内でjsonSchemaDialect値を設定できます。このデフォルトが設定されていない場合は、これらのスキーマオブジェクトに対してOASダイアレクトスキーマIDを使用する必要があります。スキーマオブジェクト内の$schemaの値は、常にデフォルトをオーバーライドします。

スキーマオブジェクトがOASドキュメントではない外部リソース（たとえば、裸のJSONスキーマリソース）から参照される場合、そのリソース内のスキーマの$schemaキーワードの値は、JSONスキーマルールに従う必要があります。

スキーマオブジェクトの例

プリミティブサンプル

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

type: string
format: email

シンプルなモデル

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

マップ/ディクショナリプロパティを持つモデル

単純な文字列から文字列へのマッピングの場合

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

type: object
additionalProperties:
  type: string

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

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

type: object
additionalProperties:
  $ref: '#/components/schemas/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

コンポジションを使用したモデル

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": [
          "message",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": [
              "rootCause"
            ],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
      - $ref: '#/components/schemas/ErrorModel'
      - type: object
        required:
        - rootCause
        properties:
          rootCause:
            type: string

ポリモーフィズムサポート付きモデル

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "petType"
        ]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/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. Note that `Dog` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/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"
            ]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      - petType
    Cat:  ## "Cat" will be used as the discriminator value
      description: A representation of a cat
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          huntingSkill:
            type: string
            description: The measured skill for hunting
            enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
        required:
        - huntingSkill
    Dog:  ## "Dog" will be used as the discriminator value
      description: A representation of a dog
      allOf:
      - $ref: '#/components/schemas/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

判別子オブジェクト

リクエストボディまたはレスポンスペイロードが複数の異なるスキーマのいずれかになる可能性がある場合、discriminatorオブジェクトを使用して、シリアル化、デシリアル化、および検証を支援できます。discriminatorは、ペイロードに関連付けられた値に基づいて、ドキュメントのコンシューマーに代替スキーマを通知するために使用される、スキーマ内の特定のオブジェクトです。

discriminatorを使用する場合、インラインスキーマは考慮されません。

固定フィールド

フィールド名	型	説明
propertyName	`文字列`	必須。ペイロード内のdiscriminator値を保持するプロパティの名前。
mapping	Map[`string`, `string`]	ペイロード値とスキーマ名または参照との間のマッピングを保持するオブジェクト。

このオブジェクトは、仕様拡張で拡張できます。

discriminatorオブジェクトは、複合キーワードoneOf、anyOf、allOfのいずれかを使用する場合にのみ有効です。

OAS 3.0では、レスポンスペイロードは、任意の数の型のいずれか1つであると記述できます。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'

つまり、ペイロードは、検証により、Cat、Dog、またはLizardで記述されたスキーマの1つと正確に一致する必要があります。この場合、discriminatorは、スキーマの複雑さによってはコストのかかる操作になる可能性がある、検証のショートカットと一致するスキーマの選択のための「ヒント」として機能する場合があります。次に、どのフィールドがどのスキーマを使用するかを正確に記述できます。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

これで、petTypeという名前のプロパティがレスポンスペイロードに存在する必要があり、その値がOASドキュメントで定義されたスキーマの名前に対応すると予想されます。したがって、レスポンスペイロードは

{
  "id": 12345,
  "petType": "Cat"
}

Catスキーマがこのペイロードと組み合わせて使用されることを示します。

discriminatorフィールドの値がスキーマ名と一致しない場合や、暗黙的なマッピングが不可能なシナリオでは、オプションのmapping定義を使用できます。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

ここで、dogのdiscriminator値は、デフォルト（暗黙的）値のDogではなく、スキーマ#/components/schemas/Dogにマップされます。discriminator値が暗黙的または明示的なマッピングと一致しない場合、スキーマを決定できず、検証は失敗する必要があります。マッピングキーは文字列値でなければなりませんが、ツールは比較のためにレスポンス値を文字列に変換してもかまいません。

anyOfコンストラクトと組み合わせて使用すると、discriminatorを使用することで、複数のスキーマが単一のペイロードを満たす可能性があるあいまいさを回避できます。

oneOfとanyOfの両方のユースケースでは、可能なすべてのスキーマを明示的にリストする必要があります。冗長性を回避するために、discriminatorを親スキーマ定義に追加でき、allOfコンストラクトの親スキーマを構成するすべてのスキーマを代替スキーマとして使用できます。

例

components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string
    Lizard:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Lizard`
        properties:
          lovesRocks:
            type: boolean

このようなペイロードは

{
  "petType": "Cat",
  "name": "misty"
}

Catスキーマを使用することを示します。同様に、このスキーマ

{
  "petType": "dog",
  "bark": "soft"
}

mapping要素の定義により、Dogにマップされます。

XMLオブジェクト

より微調整されたXMLモデル定義を可能にするメタデータオブジェクト。

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

固定フィールド

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

このオブジェクトは、仕様拡張で拡張できます。

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://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

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

<Person id="123">
    <sample:name xmlns:sample="https://example.com/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>

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

操作で使用できるセキュリティスキームを定義します。

サポートされているスキームは、HTTP認証、APIキー（ヘッダー、クッキーパラメーター、またはクエリパラメーターのいずれか）、相互TLS（クライアント証明書の使用）、RFC6749で定義されているOAuth2の一般的なフロー（暗黙的、パスワード、クライアントクレデンシャル、および認証コード）、およびOpenID Connect Discoveryです。2020年の時点で、暗黙的なフローはOAuth 2.0 Security Best Current Practiceによって廃止されようとしていることに注意してください。ほとんどのユースケースで推奨されるのは、PKCEを使用した認証コードグラントフローです。

固定フィールド

フィールド名	型	適用対象	説明
type	`文字列`	任意	必須。セキュリティスキームのタイプ。有効な値は`"apiKey"`、`"http"`、`"mutualTLS"`、`"oauth2"`、`"openIdConnect"`です。
description	`文字列`	任意	セキュリティスキームの説明。CommonMark構文をリッチテキスト表現に使用できます。
name	`文字列`	`apiKey`	必須。使用するヘッダー、クエリ、またはクッキーパラメーターの名前。
in	`文字列`	`apiKey`	必須。APIキーの場所。有効な値は`"query"`、`"header"`、または`"cookie"`です。
scheme	`文字列`	`http`	必須。RFC7235で定義されているように、Authorizationヘッダーで使用するHTTP Authorizationスキームの名前。使用する値は、IANA認証スキームレジストリに登録されている必要があります。
bearerFormat	`文字列`	`http`（`"bearer"`）	ベアラートークンがどのようにフォーマットされているかをクライアントが識別するためのヒント。ベアラートークンは通常、認証サーバーによって生成されるため、この情報は主にドキュメント目的で使用されます。
flows	OAuthフローオブジェクト	`oauth2`	必須。サポートされているフロータイプの設定情報を含むオブジェクト。
openIdConnectUrl	`文字列`	`openIdConnect`	必須。OAuth2構成値を検出するためのOpenId Connect URL。これはURLの形式でなければなりません。OpenID Connect標準では、TLSの使用が必要です。

このオブジェクトは、仕様拡張で拡張できます。

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

基本認証のサンプル

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

APIキーのサンプル

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

type: apiKey
name: api_key
in: header

JWTベアラートークンのサンプル

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}

type: http
scheme: bearer
bearerFormat: JWT

暗黙的なOAuth2のサンプル

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuthフローオブジェクト

サポートされているOAuthフローの構成を許可します。

固定フィールド

フィールド名	型	説明
implicit	OAuthフローオブジェクト	OAuth暗黙的なフローの設定
password	OAuthフローオブジェクト	OAuthリソース所有者パスワードフローの設定
clientCredentials	OAuthフローオブジェクト	OAuthクライアントクレデンシャルフローの設定。以前はOpenAPI 2.0で`application`と呼ばれていました。
authorizationCode	OAuthフローオブジェクト	OAuth認証コードフローの設定。以前はOpenAPI 2.0で`accessCode`と呼ばれていました。

このオブジェクトは、仕様拡張で拡張できます。

OAuthフローオブジェクト

サポートされているOAuthフローの設定の詳細

固定フィールド

フィールド名	型	適用対象	説明
authorizationUrl	`文字列`	`oauth2`（`"implicit"`、`"authorizationCode"`）	必須。このフローに使用する認証URL。これはURLの形式でなければなりません。OAuth2標準では、TLSの使用が必要です。
tokenUrl	`文字列`	`oauth2`（`"password"`、`"clientCredentials"`、`"authorizationCode"`）	必須。このフローに使用するトークンURL。これはURLの形式でなければなりません。OAuth2標準では、TLSの使用が必要です。
refreshUrl	`文字列`	`oauth2`	リフレッシュトークンの取得に使用するURL。これはURLの形式でなければなりません。OAuth2標準では、TLSの使用が必要です。
scopes	Map[`string`, `string`]	`oauth2`	必須。OAuth2セキュリティスキームで使用可能なスコープ。スコープ名とその簡単な説明の間のマップ。マップは空にしてもかまいません。

このオブジェクトは、仕様拡張で拡張できます。

OAuthフローオブジェクトの例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

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

この操作を実行するために必要なセキュリティスキームを一覧表示します。各プロパティに使用される名前は、コンポーネントオブジェクトのセキュリティスキームで宣言されたセキュリティスキームに対応する必要があります。

複数のスキームを含むセキュリティ要件オブジェクトでは、リクエストが承認されるためには、すべてのスキームを満たす必要があります。これにより、セキュリティ情報を伝達するために複数のクエリパラメーターまたはHTTPヘッダーが必要なシナリオをサポートできます。

セキュリティ要件オブジェクトのリストが、OpenAPI Object または Operation Object で定義されている場合、リクエストを承認するためにリスト内のセキュリティ要件オブジェクトのうち1つだけを満たす必要があります。

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

フィールドパターン	型	説明
{name}	[`string`]	各名前は、Components Object の下の Security Schemes で宣言されているセキュリティスキームに対応している必要があります。セキュリティスキームのタイプが`"oauth2"`または`"openIdConnect"`の場合、値は実行に必要なスコープ名のリストであり、認証に特定のスコープが不要な場合は、リストを空にしても構いません。他のセキュリティスキームタイプの場合、配列には、実行に必要なロール名のリストを含めることができますが、インバンドで定義または交換されることはありません。

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

非 OAuth2 セキュリティ要件

{
  "api_key": []
}

api_key: []

OAuth2 セキュリティ要件

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

petstore_auth:
- write:pets
- read:pets

オプションの OAuth2 セキュリティ

OpenAPI Object または Operation Object で定義されるような、オプションの OAuth2 セキュリティ

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

security:
  - {}
  - petstore_auth:
    - write:pets
    - read:pets

仕様拡張

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

拡張プロパティは、常に"x-"で始まるパターン化されたフィールドとして実装されます。

フィールドパターン	型	説明
^x-	任意	OpenAPI スキーマへの拡張を許可します。フィールド名は`x-`で始まる必要があります（例：`x-internal-id`）。`x-oai-`および`x-oas-`で始まるフィールド名は、OpenAPI Initiative で定義された用途のために予約されています。値は、`null`、プリミティブ、配列、またはオブジェクトにすることができます。

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

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

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

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

これに関する2つの例

Paths Object は存在しても空の場合があります。直感的ではないかもしれませんが、これは閲覧者が正しい場所にたどり着いたものの、ドキュメントにアクセスできないことを示す可能性があります。彼らは、認証に関する追加情報が含まれている可能性があるInfo Object には少なくともアクセスできます。
Path Item Object は空の場合があります。この場合、閲覧者はパスが存在することを認識しますが、その操作やパラメータを表示することはできません。これは、Paths Object からパス自体を隠すこととは異なります。ユーザーはパスの存在を認識するためです。これにより、ドキュメントプロバイダーは閲覧者が何を見ることができるかを細かく制御できます。

付録A：改訂履歴

バージョン	日付	注記
3.1.0	2021-02-15	OpenAPI 仕様 3.1.0 のリリース
3.1.0-rc1	2020-10-08	3.1 仕様の rc1
3.1.0-rc0	2020-06-18	3.1 仕様の rc0
3.0.3	2020-02-20	OpenAPI 仕様 3.0.3 のパッチリリース
3.0.2	2018-10-08	OpenAPI 仕様 3.0.2 のパッチリリース
3.0.1	2017-12-06	OpenAPI 仕様 3.0.1 のパッチリリース
3.0.0	2017-07-26	OpenAPI 仕様 3.0.0 のリリース
3.0.0-rc2	2017-06-16	3.0 仕様の rc2
3.0.0-rc1	2017-04-27	3.0 仕様の rc1
3.0.0-rc0	2017-02-28	3.0 仕様の実装者ドラフト
2.0	2015-12-31	Swagger 2.0 の OpenAPI Initiative への寄贈
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 仕様の初回リリース

OpenAPI 仕様

バージョン 3.1.0

はじめに

目次

定義

OpenAPIドキュメント

パステンプレート

メディアタイプ

HTTPステータスコード

仕様

バージョン

フォーマット

ドキュメント構造

データ型

リッチテキストフォーマット

URIにおける相対参照

URLにおける相対参照

スキーマ

OpenAPIオブジェクト

固定フィールド

情報オブジェクト

固定フィールド

情報オブジェクトの例

連絡先オブジェクト

固定フィールド

連絡先オブジェクトの例

ライセンスオブジェクト

固定フィールド

ライセンスオブジェクトの例

サーバーオブジェクト

固定フィールド

サーバーオブジェクトの例

サーバー変数オブジェクト

固定フィールド

コンポーネントオブジェクト

固定フィールド

コンポーネントオブジェクトの例

パスオブジェクト

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

パステンプレートのマッチング

Pathsオブジェクトの例

パスアイテムオブジェクト

固定フィールド

パス項目オブジェクトの例

操作オブジェクト

固定フィールド

操作オブジェクトの例

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

固定フィールド

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

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

パラメータの場所

固定フィールド

スタイル値

スタイルの例

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

リクエストボディオブジェクト

固定フィールド

リクエストボディの例

メディアタイプオブジェクト

固定フィールド

メディアタイプの例

ファイルアップロードに関する考慮事項

x-www-form-urlencodedリクエストボディのサポート

multipartコンテンツに関する特別な考慮事項

エンコーディングオブジェクト

固定フィールド

エンコーディングオブジェクトの例

レスポンスオブジェクト

固定フィールド

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

応答オブジェクトの例

レスポンスオブジェクト

固定フィールド

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

コールバックオブジェクト

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

キー式

コールバックオブジェクトの例

サンプルオブジェクト

`multipart`コンテンツに関する特別な考慮事項