OpenAPI 仕様
バージョン 3.0.3
このドキュメントにおけるキーワード "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY" および "OPTIONAL" は、すべて大文字で示されている場合に限り、BCP 14 RFC2119 RFC8174 で説明されているように解釈されるものとします。
このドキュメントは、Apache License, Version 2.0 の下でライセンスされています。
はじめに
OpenAPI 仕様（OAS）は、RESTful APIに対する標準で言語に依存しないインターフェースを定義するものであり、人間とコンピュータの両方が、ソースコード、ドキュメント、またはネットワークトラフィックの検査にアクセスすることなく、サービスの機能を検出および理解できるようにします。適切に定義されている場合、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、対話できます。
OpenAPI定義は、APIを表示するためのドキュメント生成ツール、さまざまなプログラミング言語でサーバーとクライアントを生成するためのコード生成ツール、テストツール、および他の多くのユースケースで使用できます。
目次
定義
OpenAPIドキュメント
APIを定義または記述するドキュメント（またはドキュメントのセット）。OpenAPI定義は、OpenAPI仕様を使用し、それに準拠します。
パステンプレート
パステンプレートとは、中かっこ（{}）で区切られたテンプレート式を使用して、URLパスのセクションをパスパラメータを使用して置換可能としてマークすることを指します。
パス内の各テンプレート式は、パス項目自体、および/または各パス項目の操作に含まれるパスパラメータに対応する必要があります。
メディアタイプの定義は、いくつかのリソースに分散しています。メディアタイプの定義は、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仕様は、セマンティックバージョニング2.0.0（semver）を使用してバージョン管理されており、semver仕様に従います。
semverのmajor.minorの部分（例：3.0）は、OAS機能セットを指定します。通常、.patchバージョンはこのドキュメントのエラーに対処しますが、機能セットには対処しません。OAS 3.0をサポートするツールは、すべてのOAS 3.0.*バージョンと互換性がある必要があります。パッチバージョンはツールによって考慮されるべきではなく、たとえば3.0.0と3.0.1を区別しません。
OpenAPI仕様の新しいマイナーバージョンごとに、同じメジャーバージョン内の前のマイナーバージョンに対して有効なすべてのOpenAPIドキュメントを、同等のセマンティクスを持つ新しい仕様バージョンに更新できるようにする必要があります。このような更新では、openapiプロパティを新しいマイナーバージョンに変更するだけで済む必要があります。
たとえば、有効なOpenAPI 3.0.2ドキュメントは、そのopenapiプロパティを3.1.0に変更すると、元のOpenAPI 3.0.2ドキュメントと意味的に同等の有効なOpenAPI 3.1.0ドキュメントになる必要があります。OpenAPI仕様の新しいマイナーバージョンは、この形式の後方互換性を確保するために作成する必要があります。
OAS 3.*.*と互換性のあるOpenAPIドキュメントには、使用するOASのセマンティックバージョンを指定する必須のopenapiフィールドが含まれています。（OAS 2.0ドキュメントには、トップレベルのバージョンフィールドswaggerと値"2.0"が含まれています。）
OpenAPI仕様に準拠するOpenAPIドキュメント自体は、JSONオブジェクトであり、JSONまたはYAML形式で表現できます。
たとえば、フィールドに配列の値がある場合、JSON配列表現が使用されます。
{
"field": [ 1, 2, 3 ]
}
仕様内のすべてのフィールド名は大文字と小文字が区別されます。これには、キーが大文字と小文字を区別しないと明示的に記載されている場合を除き、マップでキーとして使用されるすべてのフィールドが含まれます。
スキーマは、宣言された名前を持つ固定フィールドと、フィールド名の正規表現パターンを宣言するパターンフィールドの2種類のフィールドを公開します。
パターンフィールドには、包含オブジェクト内で一意の名前が必要です。
YAML形式とJSON形式の間でラウンドトリップする機能を保持するために、YAMLバージョン1.2といくつかの追加の制約が推奨されます。
注： APIはYAMLまたはJSON形式のいずれかのOpenAPIドキュメントで定義できますが、APIリクエストおよびレスポンスの本文およびその他のコンテンツはJSONまたはYAMLである必要はありません。
ドキュメント構造
OpenAPIドキュメントは、単一のドキュメントで構成することも、ユーザーの裁量で複数の接続された部分に分割することもできます。後者の場合、JSONスキーマの定義から、それらの部分を参照するために、仕様で$refフィールドを使用する必要があります。
ルートOpenAPIドキュメントの名前は、openapi.jsonまたはopenapi.yamlにすることを推奨します。
データ型
OASのプリミティブデータ型は、JSONスキーマ仕様ライトドラフト00でサポートされている型に基づいています。型としてのintegerもサポートされており、小数部分または指数部分のないJSON数値として定義されていることに注意してください。nullは型としてサポートされていません（代替ソリューションについてはnullableを参照）。モデルは、JSONスキーマ仕様ライトドラフト00の拡張サブセットであるスキーマオブジェクトを使用して定義されています。
プリミティブにはオプションの修飾子プロパティ：formatがあります。OASは、使用されているデータ型を詳細に定義するために、いくつかの既知の形式を使用します。ただし、ドキュメントのニーズをサポートするために、formatプロパティはオープンなstring値のプロパティであり、任意の値を持つことができます。この仕様で定義されていなくても、"email"、"uuid"などの形式を使用できます。formatプロパティを伴わない型は、JSONスキーマの型定義に従います。特定のformatを認識しないツールは、formatが指定されていないかのように、type単独にデフォルトで戻る場合があります。
OASで定義されている形式は次のとおりです。
型 |
フォーマット |
コメント |
整数 |
int32 |
符号付き32ビット |
整数 |
int64 |
符号付き64ビット（別名long） |
数値 |
float |
|
数値 |
double |
|
文字列 |
|
|
文字列 |
バイト |
base64エンコードされた文字 |
文字列 |
バイナリ |
任意のオクテットシーケンス |
ブール |
|
|
文字列 |
日付 |
full-dateで定義されているとおり - RFC3339 |
文字列 |
日付-時間 |
date-timeで定義されているとおり - RFC3339 |
文字列 |
パスワード |
UIに入力を隠すように指示します。 |
リッチテキストフォーマット
仕様全体を通して、descriptionフィールドはCommonMark Markdown形式をサポートすることが記載されています。OpenAPIツールがリッチテキストをレンダリングする場合、少なくともCommonMark 0.27で説明されているMarkdown構文をサポートする必要があります。ツールは、セキュリティ上の懸念に対処するために、一部のCommonMark機能を無視することを選択できます。
URL内の相対参照
特に明記されていない限り、URLであるすべてのプロパティは、RFC3986で定義されている相対参照である可能性があります。相対参照は、Server Objectで定義されたURLをベースURIとして解決されます。
$refで使用される相対参照は、現在のドキュメントのURLをベースURIとして使用し、JSON Referenceに従って処理されます。Reference Objectも参照してください。
スキーマ
以下の説明では、フィールドが明示的にREQUIREDであるか、MUSTまたはSHALLで記述されていない場合、OPTIONALと見なすことができます。
OpenAPIオブジェクト
これは、OpenAPIドキュメントのルートドキュメントオブジェクトです。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| openapi |
文字列 |
必須。この文字列は、OpenAPIドキュメントで使用するOpenAPI Specification versionのセマンティックバージョン番号でなければなりません。openapiフィールドは、OpenAPIドキュメントを解釈するためにツール仕様やクライアントで使用する必要があります。これは、APIのinfo.version文字列とは関係ありません。 |
| info |
情報オブジェクト |
必須。APIに関するメタデータを提供します。メタデータは、必要に応じてツールで使用できます。 |
| servers |
[Server Object] |
ターゲットサーバーへの接続情報を提供するServer Objectの配列。serversプロパティが提供されていないか、空の配列である場合、デフォルト値はurlの値が/であるServer Objectになります。 |
| paths |
パスオブジェクト |
必須。APIで利用可能なパスと操作。 |
| components |
コンポーネントオブジェクト |
仕様のさまざまなスキーマを保持するための要素。 |
| security |
[Security Requirement Object] |
API全体で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替セキュリティ要件オブジェクトが含まれています。リクエストを承認するには、セキュリティ要件オブジェクトの1つだけを満たす必要があります。個々の操作はこの定義を上書きできます。セキュリティをオプションにするには、空のセキュリティ要件({})を配列に含めることができます。 |
| tags |
[Tag Object] |
追加のメタデータを含む仕様で使用されるタグのリスト。タグの順序は、解析ツールによる順序の反映に使用できます。Operation Objectで使用されるすべてのタグを宣言する必要はありません。宣言されていないタグは、ツールロジックに基づいてランダムにまたは組織化される可能性があります。リスト内の各タグ名は一意である必要があります。 |
| externalDocs |
外部ドキュメントオブジェクト |
追加の外部ドキュメント。 |
このオブジェクトは、仕様拡張で拡張できます。
情報オブジェクト
このオブジェクトは、APIに関するメタデータを提供します。メタデータは、必要に応じてクライアントで使用でき、編集またはドキュメント生成ツールで便宜上表示できます。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| title |
文字列 |
必須。APIのタイトル。 |
| description |
文字列 |
APIの簡単な説明。CommonMark構文をリッチテキスト表現に使用できます。 |
| termsOfService |
文字列 |
APIの利用規約のURL。URL形式である必要があります。 |
| contact |
連絡先オブジェクト |
公開されたAPIの連絡先情報。 |
| license |
ライセンスオブジェクト |
公開されたAPIのライセンス情報。 |
| version |
文字列 |
必須。OpenAPIドキュメントのバージョン（OpenAPI SpecificationバージョンまたはAPI実装バージョンとは異なります）。 |
このオブジェクトは、仕様拡張で拡張できます。
Info Objectの例
{
"title": "Sample Pet Store App",
"description": "This is a sample server for a pet store.",
"termsOfService": "http://example.com/terms/",
"contact": {
"name": "API Support",
"url": "http://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
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://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": "http://www.example.com/support",
"email": "[email protected]"
}
name: API Support
url: http://www.example.com/support
email: [email protected]
ライセンスオブジェクト
公開されたAPIのライセンス情報。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| name |
文字列 |
必須。APIに使用されるライセンス名。 |
| url |
文字列 |
APIに使用されるライセンスへのURL。URL形式である必要があります。 |
このオブジェクトは、仕様拡張で拡張できます。
License Objectの例
{
"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 |
文字列 |
必須。ターゲットホストへのURL。このURLはServer Variablesをサポートしており、OpenAPIドキュメントが提供されている場所に対してホストの場所が相対的であることを示すために相対的である可能性があります。変数が{ブラケット}で名前が付けられている場合、変数の置換が行われます。 |
| description |
文字列 |
URLで指定されたホストを説明するオプションの文字列。CommonMark構文をリッチテキスト表現に使用できます。 |
| variables |
Map[string, Server Variable Object] |
変数名とその値の間のマッピング。この値は、サーバーのURLテンプレートでの置換に使用されます。 |
このオブジェクトは、仕様拡張で拡張できます。
Server Objectの例
単一のサーバーは次のように記述されます
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
}
url: https://development.gigantic-server.com/v1
description: Development server
以下は、たとえばOpenAPI Objectの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 |
文字列 |
必須。代替値が指定されていない場合に送信される、置換に使用するデフォルト値。これらの場合、パラメータ値はオプションであるため、Schema Objectのデフォルト値の処理とは異なることに注意してください。enumが定義されている場合、値は列挙値に存在する必要があります。 |
| description |
文字列 |
サーバー変数のオプションの説明。CommonMark構文をリッチテキスト表現に使用できます。 |
このオブジェクトは、仕様拡張で拡張できます。
コンポーネントオブジェクト
OASのさまざまな側面で使用できる再利用可能なオブジェクトのセットを保持します。componentsオブジェクト内で定義されたすべてのオブジェクトは、componentsオブジェクトの外部のプロパティから明示的に参照されない限り、APIに影響を与えません。
固定フィールド
このオブジェクトは、仕様拡張で拡張できます。
上記のすべての固定フィールドは、正規表現^[a-zA-Z0-9\.\-_]+$に一致するキーを使用する必要があるオブジェクトです。
フィールド名の例
User
User_1
User_Name
user-name
my.org.User
Components Objectの例
"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": "http://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: http://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 Objectの例
{
"/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'
パス項目オブジェクト
単一のパスで利用可能な操作について説明します。Path Itemは、ACL制約のために空になる可能性があります。パス自体はドキュメントビューアに公開されたままですが、どの操作とパラメータが利用可能かはわかりません。
固定フィールド
このオブジェクトは、仕様拡張で拡張できます。
パスアイテムオブジェクトの例
{
"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操作を記述します。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| タグ |
[string] |
APIドキュメント制御のためのタグのリスト。タグは、リソースやその他の修飾子による操作の論理的なグループ化に使用できます。 |
| サマリー |
文字列 |
操作の概要を説明します。 |
| 説明 |
文字列 |
操作の動作に関する詳細な説明。CommonMark構文をリッチテキスト表現に使用できます。 |
| 外部ドキュメント |
外部ドキュメントオブジェクト |
この操作に関する追加の外部ドキュメント。 |
| 操作ID |
文字列 |
操作を識別するために使用される一意の文字列。IDは、APIで記述されているすべての操作の中で一意でなければなりません。operationIdの値は大文字と小文字が区別されます。ツールやライブラリは、操作を一意に識別するためにoperationIdを使用する場合があります。そのため、一般的なプログラミングの命名規則に従うことをお勧めします。 |
| パラメータ |
[Parameter Object | Reference Object] |
この操作に適用可能なパラメータのリスト。パスアイテムでパラメータがすでに定義されている場合、新しい定義はそれをオーバーライドしますが、削除することはできません。リストには重複したパラメータを含めてはなりません。一意のパラメータは、nameとlocationの組み合わせで定義されます。このリストでは、参照オブジェクトを使用して、OpenAPIオブジェクトのcomponents/parametersで定義されているパラメータにリンクできます。 |
| リクエストボディ |
リクエストボディオブジェクト | 参照オブジェクト |
この操作に適用可能なリクエストボディ。requestBodyは、HTTP 1.1仕様RFC7231でリクエストボディのセマンティクスが明示的に定義されているHTTPメソッドでのみサポートされています。HTTP仕様があいまいな他のケースでは、requestBodyはコンシューマーによって無視されます。 |
| レスポンス |
レスポンスオブジェクト |
必須。この操作の実行から返される可能性のあるレスポンスのリスト。 |
| コールバック |
Map[string, Callback Object | Reference Object] |
親操作に関連する可能性のあるアウトオブバンドコールバックのマップ。キーは、コールバックオブジェクトの一意の識別子です。マップ内の各値は、APIプロバイダーによって開始される可能性のあるリクエストと、予期されるレスポンスを記述するコールバックオブジェクトです。 |
| 非推奨 |
ブール |
この操作が非推奨であることを宣言します。コンシューマーは、宣言された操作の使用を控える必要があります。デフォルト値はfalseです。 |
| セキュリティ |
[Security Requirement Object] |
この操作に使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のセキュリティ要件オブジェクトが含まれています。リクエストを承認するには、セキュリティ要件オブジェクトの1つだけを満たす必要があります。セキュリティをオプションにするには、空のセキュリティ要件({})を配列に含めることができます。この定義は、宣言された最上位のsecurityをオーバーライドします。最上位のセキュリティ宣言を削除するには、空の配列を使用できます。 |
| サーバー |
[Server Object] |
この操作を提供するための代替の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:
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
外部ドキュメントオブジェクト
拡張ドキュメントのために外部リソースを参照できます。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| 説明 |
文字列 |
ターゲットドキュメントの簡単な説明。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 - 特定のクッキー値をAPIに渡すために使用されます。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| 名前 |
文字列 |
必須。パラメータの名前。パラメータ名は大文字と小文字が区別されます。inが"path"の場合、nameフィールドは、pathsフィールドのパスオブジェクト内で発生するテンプレート式に対応する必要があります。詳細については、パステンプレートを参照してください。inが"header"で、nameフィールドが"Accept"、"Content-Type"、または"Authorization"の場合、パラメータ定義は無視されます。- 他のすべての場合、
nameは、inプロパティで使用されるパラメータ名に対応します。
|
| in |
文字列 |
必須。パラメータの場所。可能な値は、"query"、"header"、"path"、または"cookie"です。 |
| 説明 |
文字列 |
パラメータの簡単な説明。これには使用例を含めることができます。CommonMark構文をリッチテキスト表現に使用できます。 |
| 必須 |
ブール |
このパラメータが必須かどうかを決定します。パラメータの場所が"path"の場合、このプロパティは必須であり、その値はtrueでなければなりません。それ以外の場合、プロパティを含めることができ、デフォルト値はfalseです。 |
| 非推奨 |
ブール |
パラメータが非推奨であり、使用を移行する必要があることを指定します。デフォルト値はfalseです。 |
| allowEmptyValue |
ブール |
空の値を持つパラメータを渡す機能を設定します。これはqueryパラメータでのみ有効であり、空の値を持つパラメータを送信できます。デフォルト値はfalseです。styleが使用されていて、動作がn/a（シリアル化できない）の場合、allowEmptyValueの値は無視されます。このプロパティの使用はお勧めしません。後のリビジョンで削除される可能性があります。 |
パラメータのシリアル化のルールは、2つの方法のいずれかで指定されます。より単純なシナリオでは、schemaとstyleが、パラメータの構造と構文を記述できます。
| フィールド名 |
タイプ |
説明 |
| スタイル |
文字列 |
パラメータ値のタイプに応じて、パラメータ値がどのようにシリアル化されるかを記述します。デフォルト値（inの値に基づく）：queryの場合はform、pathの場合はsimple、headerの場合はsimple、cookieの場合はform。 |
| 展開 |
ブール |
これがtrueの場合、arrayまたはobject型のパラメータ値は、配列の各値またはマップのキーと値のペアごとに個別のパラメータを生成します。他のタイプのパラメータの場合、このプロパティは効果がありません。styleがformの場合、デフォルト値はtrueです。他のすべてのスタイルの場合、デフォルト値はfalseです。 |
| allowReserved |
ブール |
RFC3986で定義されている予約文字:/?#[]@!$&'()*+,;=を、パーセントエンコーディングなしでパラメータ値に含めることができるかどうかを決定します。このプロパティは、inの値がqueryのパラメータにのみ適用されます。デフォルト値はfalseです。 |
| スキーマ |
スキーマオブジェクト | 参照オブジェクト |
パラメータに使用されるタイプを定義するスキーマ。 |
| 例 |
任意 |
パラメータの潜在的な値の例。例は、指定されたスキーマとエンコーディングプロパティ（存在する場合）と一致する必要があります。exampleフィールドは、examplesフィールドと相互に排他的です。さらに、例を含むschemaを参照している場合、exampleの値は、スキーマによって提供される例をオーバーライドするものとします。JSONまたはYAMLで自然に表現できないメディアタイプの例を表現するために、文字列値には必要に応じてエスケープを伴う例を含めることができます。 |
| 例 |
マップ[string、例オブジェクト | 参照オブジェクト] |
パラメータの潜在的な値の例。各例には、パラメータエンコーディングで指定された正しい形式の値を含める必要があります。examplesフィールドは、exampleフィールドと相互に排他的です。さらに、例を含むschemaを参照している場合、examplesの値は、スキーマによって提供される例をオーバーライドするものとします。 |
より複雑なシナリオでは、contentプロパティで、パラメータのメディアタイプとスキーマを定義できます。パラメータには、schemaプロパティまたはcontentプロパティのいずれかを含める必要があり、両方を含めることはできません。exampleまたはexamplesがschemaオブジェクトと組み合わせて提供されている場合、例はパラメータに規定されたシリアル化戦略に従う必要があります。
| フィールド名 |
タイプ |
説明 |
| コンテンツ |
マップ[string、メディアタイプオブジェクト] |
パラメータの表現を含むマップ。キーはメディアタイプで、値はそれを記述します。マップにはエントリが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を、explodeがfalseの場合はcsv、trueの場合はmultiの値に置き換えます。 |
| simple |
array |
path, header |
RFC6570で定義されているシンプルなスタイルのパラメータ。このオプションは、OpenAPI 2.0のcollectionFormatをcsvの値に置き換えます。 |
| spaceDelimited |
array |
query |
スペースで区切られた配列の値。このオプションは、OpenAPI 2.0のcollectionFormatがssvに等しい場合に置き換えます。 |
| pipeDelimited |
array |
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
リクエストボディオブジェクト
単一のリクエストボディを記述します。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| 説明 |
文字列 |
リクエストボディの簡単な説明。これには使用例を含めることができます。CommonMark構文をリッチテキスト表現に使用してもかまいません。 |
| コンテンツ |
マップ[string、メディアタイプオブジェクト] |
必須。リクエストボディのコンテンツ。キーはメディアタイプまたはメディアタイプ範囲であり、値はそれを記述します。複数のキーに一致するリクエストの場合、最も具体的なキーのみが適用されます。例：text/plainはtext/*をオーバーライドします。 |
| 必須 |
ブール |
リクエストボディがリクエストで必須かどうかを決定します。デフォルトはfalseです。 |
このオブジェクトは、仕様拡張で拡張できます。
リクエストボディの例
参照されたモデル定義を持つリクエストボディ。
{
"description": "user to add to the system",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "User Example",
"externalValue": "http://foo.bar/examples/user-example.json"
}
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "User example in XML",
"externalValue": "http://foo.bar/examples/user-example.xml"
}
}
},
"text/plain": {
"examples": {
"user" : {
"summary": "User example in Plain text",
"externalValue": "http://foo.bar/examples/user-example.txt"
}
}
},
"*/*": {
"examples": {
"user" : {
"summary": "User example in other format",
"externalValue": "http://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: 'http://foo.bar/examples/user-example.json'
'application/xml':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example in XML
externalValue: 'http://foo.bar/examples/user-example.xml'
'text/plain':
examples:
user:
summary: User example in text plain format
externalValue: 'http://foo.bar/examples/user-example.txt'
'*/*':
examples:
user:
summary: User example in other format
externalValue: 'http://foo.bar/examples/user-example.whatever'
文字列値の配列であるボディパラメータ
{
"description": "user to add to the system",
"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
各メディアタイプオブジェクトは、そのキーで識別されるメディアタイプのスキーマと例を提供します。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| スキーマ |
スキーマオブジェクト | 参照オブジェクト |
リクエスト、レスポンス、またはパラメータのコンテンツを定義するスキーマ。 |
| 例 |
任意 |
メディアタイプの例。例オブジェクトは、メディアタイプで指定されている正しい形式である必要があります。exampleフィールドは、examplesフィールドと相互に排他的です。さらに、例を含むschemaを参照する場合、exampleの値はスキーマによって提供される例をオーバーライドします。 |
| 例 |
マップ[string、例オブジェクト | 参照オブジェクト] |
メディアタイプの例。各例オブジェクトは、メディアタイプと指定されたスキーマ（存在する場合）に一致する必要があります。examplesフィールドは、exampleフィールドと相互に排他的です。さらに、例を含むschemaを参照する場合、examplesの値はスキーマによって提供される例をオーバーライドします。 |
| エンコード |
Map[string、エンコードオブジェクト] |
プロパティ名とそのエンコード情報の間のマップ。キーはプロパティ名であり、スキーマにプロパティとして存在する必要があります。エンコードオブジェクトは、メディアタイプが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入力/出力コンテンツは、他のスキーマタイプと同じセマンティクスで記述されています。具体的には
# content transferred with base64 encoding
schema:
type: string
format: base64
# content transferred in binary (octet-stream):
schema:
type: string
format: binary
これらの例は、ファイルアップロードの入力ペイロードまたはレスポンスペイロードのいずれかに適用されます。
POST操作でファイルを送信するためのrequestBodyは、次の例のようになります。
requestBody:
content:
application/octet-stream:
schema:
# a binary file of any type
type: string
format: binary
さらに、特定のメディアタイプを指定できます
# multiple, specific media types may be specified:
requestBody:
content:
# a binary file of type png or jpeg
'image/jpeg':
schema:
type: string
format: binary
'image/png':
schema:
type: string
format: binary
複数のファイルをアップロードするには、multipartメディアタイプを使用する必要があります
requestBody:
content:
multipart/form-data:
schema:
properties:
# The property name 'file' will be used for all files.
file:
type: array
items:
type: string
format: binary
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コンテンツタイプで複合オブジェクトを渡す場合、そのようなプロパティのデフォルトのシリアライズ戦略は、エンコードオブジェクトのstyleプロパティでformとして記述されています。
multipartコンテンツに関する特別な考慮事項
リクエストボディを操作に転送する場合、multipart/form-dataをContent-Typeとして使用するのが一般的です。2.0とは対照的に、multipartコンテンツを使用する場合は、操作への入力パラメータを定義するためにschemaが必須です。これにより、複雑な構造と、複数のファイルアップロードのメカニズムのサポートが提供されます。
multipartタイプを渡す場合、コンテンツのセクションを分離するために境界を使用できます。したがって、次のデフォルトのContent-Typeがmultipartに対して定義されています
- プロパティがプリミティブ、またはプリミティブ値の配列の場合、デフォルトのContent-Typeは
text/plainです
- プロパティが複雑な場合、または複雑な値の配列の場合、デフォルトのContent-Typeは
application/jsonです
- プロパティが
type: stringで、format: binaryまたはformat: base64（つまりファイルオブジェクト）の場合、デフォルトのContent-Typeはapplication/octet-streamです
例
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:
# default Content-Type for string/binary is `application/octet-stream`
type: string
format: binary
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: '#/components/schemas/Address'
multipartリクエストボディの部分のシリアライズを制御するために、encoding属性が導入されています。この属性は、multipartおよびapplication/x-www-form-urlencodedリクエストボディにのみ適用されます。
エンコーディングオブジェクト
単一のスキーマプロパティに適用される単一のエンコード定義。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| contentType |
文字列 |
特定のプロパティをエンコードするためのContent-Type。デフォルト値はプロパティタイプによって異なります。formatがbinaryのstringの場合はapplication/octet-stream、その他のプリミティブタイプの場合はtext/plain、objectの場合はapplication/json、arrayの場合は内部タイプに基づいてデフォルトが定義されます。値は、特定のメディアタイプ（例：application/json）、ワイルドカードメディアタイプ（例：image/*）、または2つのタイプのコンマ区切りリストにすることができます。 |
| ヘッダー |
Map[string, Header Object | Reference Object] |
Content-Dispositionなどの追加情報をヘッダーとして提供できるようにするマップ。Content-Typeは別々に記述されており、このセクションでは無視する必要があります。このプロパティは、リクエストボディのメディアタイプがmultipartではない場合は無視する必要があります。 |
| スタイル |
文字列 |
特定のプロパティ値がそのタイプに応じてどのようにシリアライズされるかを記述します。パラメータオブジェクトのstyleプロパティの詳細を参照してください。動作は、デフォルト値を含むqueryパラメータと同じ値に従います。このプロパティは、リクエストボディのメディアタイプがapplication/x-www-form-urlencodedではない場合は無視する必要があります。 |
| explode |
ブール |
これがtrueの場合、arrayまたはobjectタイプのプロパティ値は、配列の各値、またはマップのキーと値のペアに対して個別のパラメータを生成します。他のタイプのプロパティの場合、このプロパティは効果がありません。styleがformの場合、デフォルト値はtrueです。他のすべてのスタイルの場合、デフォルト値はfalseです。このプロパティは、リクエストボディのメディアタイプがapplication/x-www-form-urlencodedではない場合は無視する必要があります。 |
| allowReserved |
ブール |
パラメータ値が、RFC3986で定義されている予約文字:/?#[]@!$&'()*+,;=をパーセントエンコーディングなしで含めることを許可する必要があるかどうかを決定します。デフォルト値はfalseです。このプロパティは、リクエストボディのメディアタイプがapplication/x-www-form-urlencodedではない場合は無視する必要があります。 |
このオブジェクトは、仕様拡張で拡張できます。
エンコードオブジェクトの例
requestBody:
content:
multipart/mixed:
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:
# default is application/octet-stream, need to declare an image type only!
type: string
format: binary
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は、仕様で個別にカバーされていないすべてのHTTPコードのデフォルトのレスポンスオブジェクトとして使用できます。
Responses Objectには、少なくとも1つのレスポンスコードが含まれている必要があり、成功した操作呼び出しのレスポンスである必要があります。
固定フィールド
パターン化されたフィールド
| フィールドパターン |
タイプ |
説明 |
| HTTPステータスコード |
レスポンスオブジェクト | 参照オブジェクト |
プロパティ名には任意のHTTPステータスコードを使用できますが、HTTPステータスコードごとに1つのプロパティのみを使用し、そのHTTPステータスコードに対する予期されるレスポンスを記述します。参照オブジェクトは、OpenAPIオブジェクトのcomponents/responsesセクションで定義されているレスポンスにリンクできます。このフィールドは、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": "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を識別するために、実行時に評価される式です。
パターン化されたフィールド
| フィールドパターン |
タイプ |
説明 |
| {式} |
パス項目オブジェクト |
コールバックリクエストと予期されるレスポンスを定義するために使用されるパスアイテムオブジェクト。完全な例が利用可能です。 |
このオブジェクトは、仕様拡張で拡張できます。
キー式
パスアイテムオブジェクトを識別するキーは、ランタイム式であり、ランタイムHTTPリクエスト/レスポンスのコンテキストで評価して、コールバックリクエストに使用するURLを識別できます。簡単な例は、$request.body#/urlです。ただし、ランタイム式を使用すると、HTTPメッセージ全体にアクセスできます。これには、JSON Pointer RFC6901が参照できる本文の任意の部分へのアクセスが含まれます。
たとえば、次のHTTPリクエストの場合
POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187
{
"failedUrl" : "http://clientdomain.com/failed",
"successUrls" : [
"http://clientdomain.com/fast",
"http://clientdomain.com/medium",
"http://clientdomain.com/slow"
]
}
201 Created
Location: http://example.org/subscription/1
次の例は、コールバック操作にeventTypeという名前のパスパラメーターと、queryUrlという名前のクエリパラメーターがあることを前提として、さまざまな式がどのように評価されるかを示しています。
コールバックオブジェクトの例
次の例では、ユーザーが提供した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
例オブジェクト
固定フィールド
| フィールド名 |
タイプ |
説明 |
| 概要 |
文字列 |
例の簡単な説明。 |
| 説明 |
文字列 |
例の詳細な説明。CommonMark構文を使用して、リッチテキスト表現を使用できます。 |
| 値 |
任意 |
埋め込みリテラル例。valueフィールドとexternalValueフィールドは相互に排他的です。JSONまたはYAMLで自然に表現できないメディアタイプの例を表すには、文字列値を使用して例を含め、必要に応じてエスケープします。 |
| 外部値 |
文字列 |
リテラル例を指すURL。これにより、JSONまたはYAMLドキュメントに簡単に含めることができない例を参照する機能が提供されます。valueフィールドとexternalValueフィールドは相互に排他的です。 |
このオブジェクトは、仕様拡張で拡張できます。
すべての場合において、例の値は、関連する値の型スキーマと互換性があることが期待されます。ツール実装では、互換性を自動的に検証し、互換性がない場合は例の値を拒否することがあります。
オブジェクト例
リクエストボディ内
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: 'http://example.org/examples/address-example.xml'
'text/plain':
examples:
textExample:
summary: This is a text example
externalValue: 'http://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'
リンクオブジェクト
リンクオブジェクトは、レスポンスの可能な設計時リンクを表します。リンクの存在は、呼び出し側がそれを正常に呼び出すことができることを保証するものではなく、レスポンスと他の操作の間で既知の関係とトラバーサルメカニズムを提供します。
動的リンク（つまり、レスポンスペイロード内で提供されるリンク）とは異なり、OASリンクメカニズムでは、ランタイムレスポンスにリンク情報が必要ありません。
リンクの計算と実行手順の提供には、ランタイム式を使用して、操作の値にアクセスし、リンクされた操作を呼び出す際にパラメーターとして使用します。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| operationRef |
文字列 |
OAS操作への相対または絶対URI参照。このフィールドはoperationIdフィールドと相互に排他的であり、操作オブジェクトを指している必要があります。相対的なoperationRef値を使用して、OpenAPI定義内の既存の操作オブジェクトを検索できます。 |
| operationId |
文字列 |
一意のoperationIdで定義された、解決可能な既存のOAS操作の名前。このフィールドはoperationRefフィールドと相互に排他的です。 |
| パラメーター |
マップ[string、Any | {式}] |
operationIdで指定された操作、またはoperationRef経由で識別された操作に渡すパラメーターを表すマップ。キーは使用するパラメーター名であり、値は定数またはリンクされた操作に評価して渡される式です。パラメーター名は、異なる場所で同じパラメーター名を使用する操作の場合、パラメーターの場所 [{in}.]{name}を使用して修飾できます（例：path.id）。 |
| リクエストボディ |
Any | {式} |
ターゲット操作を呼び出すときにリクエストボディとして使用するリテラル値または{式}。 |
| 説明 |
文字列 |
リンクの説明。CommonMark構文を使用して、リッチテキスト表現を使用できます。 |
| サーバー |
サーバーオブジェクト |
ターゲット操作で使用されるサーバーオブジェクト。 |
このオブジェクトは、仕様拡張で拡張できます。
リンクされた操作は、operationRefまたはoperationIdのいずれかを使用して識別する必要があります。operationIdの場合、OASドキュメントのスコープ内で一意であり、解決される必要があります。名前が衝突する可能性があるため、外部参照を含む仕様ではoperationRef構文が推奨されます。
例
$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は操作オブジェクトのオプションフィールドです）、相対的なoperationRefを使用して参照することもできます。
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メッセージ内でのみ利用可能になる情報に基づいて値を定義できます。このメカニズムは、リンクオブジェクトとコールバックオブジェクトで使用されます。
ランタイム式は、次の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はRFC 6901から取得され、charはRFC 7159から取得され、tokenはRFC 7230から取得されます。
name識別子はcase-sensitiveですが、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 |
単一のヘッダー値のみが利用可能です |
ランタイム式は、参照された値の型を保持します。式は、式を{}中かっこで囲むことで、文字列値に埋め込むことができます。
ヘッダーオブジェクトは、次の変更を加えて、パラメーターオブジェクトの構造に従います
nameは指定しないでください。対応するheadersマップで指定されます。inは指定しないでください。暗黙的にheader内にあります。- 場所によって影響を受けるすべての特性は、
headerの場所にも適用できる必要があります（例：style）。
型が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
タグオブジェクト
操作オブジェクトで使用される単一のタグにメタデータを追加します。操作オブジェクトインスタンスで定義されたタグごとにタグオブジェクトを持つことは必須ではありません。
固定フィールド
このオブジェクトは、仕様拡張で拡張できます。
タグオブジェクトの例
{
"name": "pet",
"description": "Pets operations"
}
name: pet
description: Pets operations
参照オブジェクト
仕様内で、内部および外部で他のコンポーネントを参照できるようにする単純なオブジェクト。
参照オブジェクトは、JSON参照によって定義され、同じ構造、動作、および規則に従います。
この仕様では、参照解決はJSONスキーマ仕様ではなく、JSON参照仕様で定義されているとおりに実行されます。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| $ref |
文字列 |
必須。参照文字列。 |
このオブジェクトは追加のプロパティで拡張できず、追加されたプロパティはすべて無視されるものとします。
参照オブジェクトの例
{
"$ref": "#/components/schemas/Pet"
}
$ref: '#/components/schemas/Pet'
相対スキーマドキュメントの例
{
"$ref": "Pet.json"
}
$ref: Pet.yaml
埋め込みスキーマを持つ相対ドキュメントの例
{
"$ref": "definitions.json#/Pet"
}
$ref: definitions.yaml#/Pet
スキーマオブジェクト
スキーマオブジェクトは、入力および出力データ型の定義を可能にします。これらの型はオブジェクトにできますが、プリミティブや配列にもできます。このオブジェクトは、JSON Schema Specification Wright Draft 00 の拡張サブセットです。
プロパティの詳細については、JSON Schema Core および JSON Schema Validation を参照してください。特に明記されていない限り、プロパティの定義は JSON Schema に準拠します。
プロパティ
次のプロパティは、JSON Schema 定義から直接取得されており、同じ仕様に従います。
- title
- multipleOf
- maximum
- exclusiveMaximum
- minimum
- exclusiveMinimum
- maxLength
- minLength
- pattern (この文字列は、Ecma-262 Edition 5.1 正規表現の方言に従って、有効な正規表現であるべきです)
- maxItems
- minItems
- uniqueItems
- maxProperties
- minProperties
- required
- enum
次のプロパティは、JSON Schema 定義から取得されていますが、その定義は OpenAPI 仕様に合わせて調整されました。
- type - 値は文字列である必要があります。配列による複数の型はサポートされていません。
- allOf - インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。
- oneOf - インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。
- anyOf - インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。
- not - インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。
- items - 値はオブジェクトであり、配列であってはなりません。インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。
type が array の場合、items は存在する必要があります。
- properties - プロパティ定義は、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります（インラインまたは参照）。
- additionalProperties - 値はブール値またはオブジェクトにすることができます。インラインまたは参照されたスキーマは、標準の JSON スキーマではなく、スキーマオブジェクトである必要があります。JSON Schema と一致して、
additionalProperties のデフォルトは true です。
- description - リッチテキスト表現には、CommonMark 構文を使用できます。
- format - 詳細については、データ型形式を参照してください。JSON Schema で定義された形式に依存しますが、OAS はいくつかの追加の定義済み形式を提供します。
- default - デフォルト値は、値が提供されていない場合にスキーマの値として入力のコンシューマーによって想定されるものを表します。JSON Schema とは異なり、値は同じレベルで定義されたスキーマオブジェクトの定義された型に準拠する必要があります。たとえば、
type が string の場合、default は "foo" にできますが、1 にすることはできません。
または、スキーマオブジェクトを使用できる場合は常に、代わりに 参照オブジェクトを使用できます。これにより、インラインで定義するのではなく、定義を参照できます。
ここで言及されていない JSON Schema 仕様で定義された追加のプロパティは、厳密にはサポートされていません。
JSON Schema サブセットフィールド以外に、次のフィールドを追加のスキーマドキュメントに使用できます。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| nullable |
ブール |
true の値は、type キーワードによって指定された許可される型に "null" を追加します。これは、type が同じスキーマオブジェクト内で明示的に定義されている場合に限ります。他のスキーマオブジェクトの制約は、定義された動作を保持するため、null を値として使用することを許可しない場合があります。false の値は、指定された型またはデフォルトの型を変更しません。デフォルト値は false です。 |
| discriminator |
判別子オブジェクト |
ポリモーフィズムのサポートを追加します。判別子は、ペイロード記述を満たす可能性のある他のスキーマを区別するために使用されるオブジェクト名です。詳細については、構成と継承を参照してください。 |
| readOnly |
ブール |
スキーマの "properties" 定義にのみ関連します。プロパティを「読み取り専用」として宣言します。つまり、レスポンスの一部として送信される可能性がありますが、リクエストの一部として送信すべきではありません。プロパティが readOnly を true としてマークされ、required リストにある場合、required はレスポンスのみに影響します。プロパティを readOnly と writeOnly の両方を true としてマークすることはできません。デフォルト値は false です。 |
| writeOnly |
ブール |
スキーマの "properties" 定義にのみ関連します。プロパティを「書き込み専用」として宣言します。したがって、リクエストの一部として送信される可能性がありますが、レスポンスの一部として送信すべきではありません。プロパティが writeOnly を true としてマークされ、required リストにある場合、required はリクエストのみに影響します。プロパティを readOnly と writeOnly の両方を true としてマークすることはできません。デフォルト値は false です。 |
| xml |
XMLオブジェクト |
これはプロパティスキーマでのみ使用できます。ルートスキーマには影響しません。このプロパティの XML 表現を記述するための追加のメタデータを追加します。 |
| externalDocs |
外部ドキュメントオブジェクト |
このスキーマに関する追加の外部ドキュメント。 |
| example |
任意 |
このスキーマのインスタンスの例を含めるためのフリーフォームプロパティ。JSON または YAML で自然に表現できない例を表すには、必要な場合にエスケープを使用して、例を含む文字列値を使用できます。 |
| deprecated |
ブール |
スキーマが非推奨であり、使用から移行する必要があることを指定します。デフォルト値は false です。 |
このオブジェクトは、仕様拡張で拡張できます。
構成と継承（ポリモーフィズム）
OpenAPI 仕様では、JSON Schema の allOf プロパティを使用してモデル定義を結合および拡張できるため、事実上モデル構成が提供されます。allOf は、独立して検証されますが、一緒に単一のオブジェクトを構成するオブジェクト定義の配列を受け取ります。
構成はモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。ポリモーフィズムをサポートするために、OpenAPI 仕様では discriminator フィールドが追加されています。使用すると、discriminator は、モデルの構造を検証するスキーマ定義を決定するプロパティの名前になります。したがって、discriminator フィールドは必須フィールドである必要があります。継承インスタンスの判別子の値を定義するには、2 つの方法があります。
- スキーマ名を使用します。
- 新しい値でプロパティをオーバーライドして、スキーマ名をオーバーライドします。新しい値が存在する場合、これはスキーマ名よりも優先されます。したがって、指定された ID を持たないインラインスキーマ定義は、ポリモーフィズムでは使用できません。
XML モデリング
xml プロパティを使用すると、JSON 定義を XML に変換するときに追加の定義が可能になります。XML オブジェクトには、利用可能なオプションに関する追加情報が含まれています。
スキーマオブジェクトの例
プリミティブサンプル
{
"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 オブジェクトを使用して、シリアル化、デシリアル化、および検証を支援できます。判別子は、それに関連付けられた値に基づいて代替スキーマの仕様をコンシューマーに通知するために使用されるスキーマ内の特定のオブジェクトです。
判別子を使用する場合、インラインスキーマは考慮されません。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| propertyName |
文字列 |
必須。判別子の値を保持するペイロード内のプロパティの名前。 |
| mapping |
Map[string, string] |
ペイロード値とスキーマ名または参照の間のマッピングを保持するオブジェクト。 |
判別子オブジェクトは、複合キーワード oneOf、anyOf、allOf のいずれかを使用する場合にのみ有効です。
OAS 3.0 では、レスポンスペイロードを任意の数の型のいずれかであると正確に記述できます。
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
これは、ペイロードが検証によって、Cat、Dog、または Lizard で記述されたスキーマのいずれか 1 つと正確に一致する必要があることを意味します。この場合、判別子は、スキーマの複雑さによってはコストのかかる操作となる可能性のある、一致するスキーマの検証と選択をショートカットする「ヒント」として機能します。次に、どのフィールドがどのスキーマを使用するかを示すかを正確に記述できます。
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
discriminator:
propertyName: petType
ここで期待されることは、petType という名前のプロパティがレスポンスペイロードに存在する必要があり、その値が OAS ドキュメントで定義されたスキーマの名前に対応することです。したがって、レスポンスペイロード
{
"id": 12345,
"petType": "Cat"
}
は、このペイロードと組み合わせて Cat スキーマを使用することを示すことになります。
判別子フィールドの値がスキーマ名と一致しない場合、または暗黙的なマッピングが不可能なシナリオでは、オプションの 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 の判別子値が、デフォルト（暗黙的）値の Dog ではなく、スキーマ #/components/schemas/Dog にマッピングされます。判別子値が暗黙的または明示的なマッピングと一致しない場合、スキーマを決定できず、検証は失敗するべきです。マッピングキーは文字列値である必要がありますが、ツールは応答値を比較のために文字列に変換する場合があります。
anyOf コンストラクトと組み合わせて使用すると、判別子を使用することで、複数のスキーマが単一のペイロードを満たす可能性がある曖昧さを回避できます。
oneOf と anyOf の両方のユースケースで、考えられるすべてのスキーマを明示的にリストする必要があります。冗長性を避けるために、判別子を親スキーマ定義に追加でき、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"
}
は、mappings 要素の定義により、Dog にマッピングされます。
XMLオブジェクト
より細かい調整された XML モデル定義を可能にするメタデータオブジェクト。
配列を使用する場合、XML 要素名は（単数形/複数形の場合）推論されず、name プロパティを使用してその情報を追加する必要があります。期待される動作については、例を参照してください。
固定フィールド
| フィールド名 |
タイプ |
説明 |
| name |
文字列 |
記述されたスキーマプロパティに使用される要素/属性の名前を置き換えます。items内で定義された場合、リスト内の個々のXML要素の名前に影響します。typeがarrayの場合（itemsの外側）、ラッパー要素に影響し、wrappedがtrueの場合のみ影響します。wrappedがfalseの場合、無視されます。 |
| namespace |
文字列 |
名前空間定義のURI。値は絶対URI形式である必要があります。 |
| prefix |
文字列 |
nameに使用されるプレフィックス。 |
| attribute |
ブール |
プロパティ定義が要素ではなく属性に変換されるかどうかを宣言します。デフォルト値はfalseです。 |
| wrapped |
ブール |
配列定義でのみ使用できます。配列がラップされているか（例：<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": "http://example.com/schema/sample",
"prefix": "sample"
}
}
}
}
}
Person:
type: object
properties:
id:
type: integer
format: int32
xml:
attribute: true
name:
type: string
xml:
namespace: http://example.com/schema/sample
prefix: sample
<Person id="123">
<sample:name xmlns:sample="http://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キー（ヘッダー、クッキーパラメータ、またはクエリパラメータのいずれか）、RFC6749で定義されているOAuth2の一般的なフロー（暗黙的、パスワード、クライアント資格情報、認可コード）、およびOpenID Connect Discoveryです。
固定フィールド
| フィールド名 |
タイプ |
適用対象 |
説明 |
| type |
文字列 |
任意 |
必須。セキュリティスキームのタイプ。有効な値は、"apiKey"、"http"、"oauth2"、"openIdConnect"です。 |
| description |
文字列 |
任意 |
セキュリティスキームの簡単な説明。CommonMark構文をリッチテキスト表現に使用できます。 |
| name |
文字列 |
apiKey |
必須。使用するヘッダー、クエリ、またはクッキーパラメータの名前。 |
| in |
文字列 |
apiKey |
必須。APIキーの場所。有効な値は、"query"、"header"、または"cookie"です。 |
| scheme |
文字列 |
http |
必須。RFC7235で定義されているように、IANA認証スキームレジストリに登録されている値をAuthorizationヘッダーで使用されるHTTP認証スキームの名前。 |
| bearerFormat |
文字列 |
http（"bearer"） |
ベアラートークンがどのようにフォーマットされるかをクライアントに識別させるためのヒント。ベアラートークンは通常、認証サーバーによって生成されるため、この情報は主にドキュメントの目的で使用されます。 |
| flows |
OAuthフローオブジェクト |
oauth2 |
必須。サポートされているフロータイプの構成情報を含むオブジェクト。 |
| openIdConnectUrl |
文字列 |
openIdConnect |
必須。OAuth2構成値を検出するためのOpenId Connect URL。これはURL形式である必要があります。 |
このオブジェクトは、仕様拡張で拡張できます。
セキュリティスキームオブジェクトの例
基本認証の例
{
"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形式である必要があります。 |
| tokenUrl |
文字列 |
oauth2（"password"、"clientCredentials"、"authorizationCode"） |
必須。このフローに使用されるトークンURL。これはURL形式である必要があります。 |
| refreshUrl |
文字列 |
oauth2 |
リフレッシュトークンを取得するために使用するURL。これはURL形式である必要があります。 |
| 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オブジェクトまたは操作オブジェクトでセキュリティ要件オブジェクトのリストが定義されている場合、リクエストを承認するためにリスト内のセキュリティ要件オブジェクトの1つだけを満たす必要があります。
パターン化されたフィールド
| フィールドパターン |
タイプ |
説明 |
| {name} |
[string] |
各名前は、コンポーネントオブジェクトのセキュリティスキームで宣言されたセキュリティスキームに対応している必要があります。セキュリティスキームが"oauth2"または"openIdConnect"タイプの場合、値は実行に必要なスコープ名のリストであり、認可が特定のスコープを必要としない場合はリストを空にできます。他のセキュリティスキームタイプの場合、配列は空である必要があります。 |
セキュリティ要件オブジェクトの例
非OAuth2セキュリティ要件
{
"api_key": []
}
api_key: []
OAuth2セキュリティ要件
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
petstore_auth:
- write:pets
- read:pets
オプションのOAuth2セキュリティ
OpenAPIオブジェクトまたは操作オブジェクトで定義されるオプションのOAuth2セキュリティ
{
"security": [
{},
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
security:
- {}
- petstore_auth:
- write:pets
- read:pets
仕様拡張
OpenAPI仕様はほとんどのユースケースに対応しようとしていますが、特定の時点で仕様を拡張するために追加のデータを追加できます。
拡張プロパティは、常に"x-"で始まるパターン化されたフィールドとして実装されます。
| フィールドパターン |
タイプ |
説明 |
| ^x- |
任意 |
OpenAPIスキーマの拡張を許可します。フィールド名はx-で始まる必要があります。たとえば、x-internal-idなどです。値は、null、プリミティブ、配列、またはオブジェクトにすることができます。任意の有効なJSON形式の値を持つことができます。 |
拡張機能は、利用可能なツールでサポートされている場合もあれば、そうでない場合もありますが、リクエストされたサポートを追加するために拡張することもできます（ツールが内部またはオープンソースの場合）。
セキュリティフィルタリング
OpenAPI仕様の一部のオブジェクトは、APIドキュメントの中核となるにもかかわらず、宣言されて空のままになったり、完全に削除されたりする場合があります。
その理由は、ドキュメントに対する追加のアクセス制御レイヤーを許可するためです。仕様自体の一部ではありませんが、特定のライブラリは、何らかの形式の認証/認可に基づいてドキュメントの一部へのアクセスを許可する場合があります。
この例を2つ挙げます
- パスオブジェクトは空にすることができます。直感的ではないかもしれませんが、これにより、閲覧者は適切な場所にたどり着いたが、ドキュメントにアクセスできないことを知ることができます。彼らは、認証に関する追加情報が含まれている可能性のある情報オブジェクトには引き続きアクセスできます。
- パスアイテムオブジェクトは空にすることができます。この場合、閲覧者はパスが存在することを認識しますが、その操作やパラメータを見ることはできません。これは、パスオブジェクトからパス自体を隠すのとは異なります。ユーザーはパスの存在を認識するためです。これにより、ドキュメントプロバイダーは、閲覧者が何を見ることができるかを細かく制御できます。
付録A：改訂履歴
| バージョン |
日付 |
注記 |
| 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イニシアチブへの寄贈 |
| 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仕様の最初のリリース |