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 Specification (OAS) は、RESTful API の標準的な言語に依存しないインターフェースを定義しており、これにより人間とコンピューターの両方が、ソースコード、ドキュメントへのアクセス、またはネットワークトラフィックの検査なしに、サービスの機能を発見し理解することができます。適切に定義されていれば、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、操作することができます。

OpenAPI定義は、APIを表示するドキュメント生成ツール、様々なプログラミング言語でサーバーやクライアントを生成するコード生成ツール、テストツール、その他多くのユースケースで利用できます。

定義

OpenAPIドキュメント

APIを定義または記述するドキュメント（または一連のドキュメント）。OpenAPI定義はOpenAPI Specificationを使用し、それに準拠します。

パスのテンプレート化

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

パス内の各テンプレート式は、Path Item自体、および/または各Path ItemのOperationに含まれるパスパラメータに対応していなければなりません。

メディアタイプ

メディアタイプ定義はいくつかのリソースにまたがって存在します。メディアタイプ定義は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 Status Code Registryにリストされています。

仕様

バージョン

OpenAPI SpecificationはSemantic Versioning 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 Specification の新しいマイナーバージョンごとに、同じメジャーバージョン内の以前のマイナーバージョンに対して有効な OpenAPI ドキュメントは、同等のセマンティクスで新しい仕様バージョンに更新できるものとします。このような更新では、openapi プロパティを新しいマイナーバージョンに変更するだけでよいものとします。

例えば、有効な OpenAPI 3.0.2 ドキュメントは、その openapi プロパティを 3.1.0 に変更すると、元の OpenAPI 3.0.2 ドキュメントと意味的に同等の、有効な OpenAPI 3.1.0 ドキュメントとなるものとします。OpenAPI Specification の新しいマイナーバージョンは、この形式の後方互換性を確保するように記述されなければなりません。

OAS 3.*.* に互換性のある OpenAPI ドキュメントには、使用する OAS のセマンティックバージョンを指定する必須の openapi フィールドが含まれます。(OAS 2.0 ドキュメントには、トップレベルのバージョンフィールド swagger と値 "2.0" が含まれます。)

フォーマット

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

例えば、フィールドが配列値を持つ場合、JSON配列表現が使用されます。

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

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

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

パターン化されたフィールドは、そのコンテナオブジェクト内で一意の名前を持たなければなりません。

YAMLとJSON形式の間で往復する能力を維持するため、YAMLバージョン1.2と、いくつかの追加の制約が推奨されます。

タグはJSON Schemaルールセットで許可されているものに限定されなければなりません。
YAMLマップで使用されるキーは、YAML Failsafeスキーマルールセットで定義されているとおり、スカラー文字列に限定されなければなりません。

注: APIはYAMLまたはJSON形式のOpenAPIドキュメントで定義できますが、APIのリクエストおよびレスポンスボディやその他のコンテンツがJSONまたはYAMLである必要はありません。

ドキュメント構造

OpenAPIドキュメントは、単一のドキュメントで構成されることも、ユーザーの裁量により複数の接続された部分に分割されることもあります。後者の場合、JSON Schemaの定義に従って、これらの部分を参照するために仕様内で$refフィールドを使用しなければなりません。

ルートのOpenAPIドキュメントはopenapi.jsonまたはopenapi.yamlと命名することが推奨されます。

データ型

OASにおけるプリミティブデータ型は、JSON Schema Specification Wright Draft 00でサポートされている型に基づいています。型としてのintegerもサポートされており、小数部や指数部を持たないJSON数値として定義されています。nullは型としてサポートされていません（代替ソリューションについてはnullableを参照してください）。モデルは、JSON Schema Specification Wright Draft 00の拡張サブセットであるSchema Objectを使用して定義されます。

プリミティブはオプションの修飾子プロパティformatを持っています。OASは、使用されているデータ型を詳細に定義するために、いくつかの既知のフォーマットを使用します。しかし、ドキュメントのニーズをサポートするために、formatプロパティはオープンなstring値のプロパティであり、任意の値を持ち得ます。"email"、"uuid"などのフォーマットは、この仕様で未定義であっても使用できます。formatプロパティを伴わない型は、JSON Schemaの型定義に従います。特定のformatを認識しないツールは、formatが指定されていないかのように、単独でtypeにデフォルト設定してもよいでしょう。

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

`タイプ`	`フォーマット`	コメント
`整数`	`int32`	符号付き32ビット
`整数`	`int64`	符号付き 64 ビット（別名 long）
`数`	`浮動小数点数`
`数`	`ダブル`
`文字列`
`文字列`	`byte`	base64エンコードされた文字
`文字列`	`バイナリ`	任意のオクテットシーケンス
`ブール値`
`文字列`	`日付`	`full-date`によって定義される - RFC3339
`文字列`	`日時`	`date-time`によって定義される - RFC3339
`文字列`	`パスワード`	UIに入力を隠すためのヒント。

リッチテキスト書式設定

仕様全体を通して、description フィールドは CommonMark マークダウン書式設定をサポートすると記載されています。OpenAPI ツールがリッチテキストをレンダリングする場合、最低でも CommonMark 0.27 で説明されているマークダウン構文をサポートしなければなりません。ツールはセキュリティ上の懸念に対処するために、一部の CommonMark 機能を無視しても構いません。

URL内の相対参照

特に指定がない限り、URLであるすべてのプロパティはRFC3986で定義されている相対参照であっても構いません。相対参照は、Base URIとしてServer Objectで定義されたURLを使用して解決されます。

$refで使われる相対参照は、現在のドキュメントのURLをベースURIとして、JSON Referenceに従って処理されます。Reference Objectも参照してください。

スキーマ

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

OpenAPI オブジェクト

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

固定フィールド

フィールド名	タイプ	説明
openapi	`文字列`	必須。この文字列は、OpenAPIドキュメントが使用するOpenAPI Specificationバージョンのセマンティックバージョン番号でなければなりません。`openapi`フィールドは、ツール仕様およびクライアントがOpenAPIドキュメントを解釈するために使用すべきです。これはAPIの`info.version`文字列とは関係ありません。
情報	情報オブジェクト	必須。APIに関するメタデータを提供します。メタデータは、必要に応じてツールによって使用されることがあります。
サーバー	[サーバーオブジェクト]	ターゲットサーバーへの接続情報を提供するServer Objectsの配列。`servers`プロパティが指定されていない、または空の配列である場合、デフォルト値はServer Objectで、urlの値は`/`になります。
パス	パスオブジェクト	必須。APIで利用可能なパスと操作。
コンポーネント	コンポーネントオブジェクト	仕様の様々なスキーマを保持するための要素。
セキュリティ	[セキュリティ要件オブジェクト]	API全体で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のセキュリティ要件オブジェクトが含まれます。リクエストを認証するには、セキュリティ要件オブジェクトのいずれか1つを満たすだけで十分です。個々の操作はこの定義を上書きできます。セキュリティをオプションにするには、空のセキュリティ要件 (`{}`) を配列に含めることができます。
タグ	[タグオブジェクト]	仕様によって使用されるタグのリストで、追加のメタデータが付随します。タグの順序は、解析ツールによってその順序が反映されるように使用できます。Operation Objectによって使用されるすべてのタグが宣言されている必要はありません。宣言されていないタグは、ランダムに、またはツールのロジックに基づいて整理されても構いません。リスト内の各タグ名は一意でなければなりません。
外部ドキュメント	外部ドキュメントオブジェクト	追加の外部ドキュメント。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

情報オブジェクト

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

固定フィールド

フィールド名	タイプ	説明
タイトル	`文字列`	必須。APIのタイトル。
説明	`文字列`	APIの簡単な説明。CommonMark構文はリッチテキスト表現に使用されても構いません。
利用規約	`文字列`	APIの利用規約へのURL。URLの形式でなければなりません。
連絡先	連絡先オブジェクト	公開されたAPIの連絡先情報。
ライセンス	ライセンスオブジェクト	公開されたAPIのライセンス情報。
バージョン	`文字列`	必須。OpenAPIドキュメントのバージョン（OpenAPI SpecificationバージョンやAPI実装バージョンとは異なります）。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

情報オブジェクトの例

{
  "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の連絡先情報。

固定フィールド

フィールド名	タイプ	説明
名前	`文字列`	担当者/組織の識別名。
URL	`文字列`	連絡先情報へのURL。URLの形式でなければなりません。
メール	`文字列`	連絡担当者/組織のメールアドレス。メールアドレスの形式でなければなりません。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

連絡先オブジェクトの例

{
  "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のライセンス情報。

固定フィールド

フィールド名	タイプ	説明
名前	`文字列`	必須。APIに使用されるライセンス名。
URL	`文字列`	APIに使用されるライセンスへのURL。URLの形式でなければなりません。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

{
  "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はサーバー変数をサポートし、OpenAPIドキュメントが提供されている場所を基準としたホストの場所を示すために相対パスであっても構いません。`{`括弧`}`内に変数名がある場合、変数の置換が行われます。
説明	`文字列`	URLで指定されたホストを記述するオプションの文字列。CommonMark構文はリッチテキスト表現に使用されても構いません。
変数	Map[`string`, Server Variable Object]	変数名とその値の間のマッピング。値はサーバーのURLテンプレート内の置換に使用されます。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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

{
  "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`]	代替の置換オプションが限られたセットから選ばれる場合に使用される文字列値の列挙。配列は空であるべきではありません。
デフォルト	`文字列`	必須。置換に使用するデフォルト値。代替値が提供されない場合に送信されます。この動作は、Schema Objectのデフォルト値の扱いとは異なります。なぜなら、後者の場合、パラメーター値はオプションだからです。`enum`が定義されている場合、値はenumの値に存在すべきです。
説明	`文字列`	サーバー変数に対するオプションの説明。CommonMark構文はリッチテキスト表現に使用されても構いません。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

OASのさまざまな側面のための再利用可能なオブジェクトのセットを保持します。コンポーネントオブジェクト内で定義されたすべてのオブジェクトは、コンポーネントオブジェクトの外部のプロパティから明示的に参照されない限り、APIに影響を与えません。

固定フィールド

フィールド名	タイプ	説明
スキーマ	Map[`string`, Schema Object \| Reference Object]	再利用可能なスキーマオブジェクトを保持するためのオブジェクト。
レスポンス	Map[`string`, Response Object \| Reference Object]	再利用可能なレスポンスオブジェクトを保持するためのオブジェクト。
パラメーター	Map[`string`, Parameter Object \| Reference Object]	再利用可能なパラメーターオブジェクトを保持するためのオブジェクト。
例	Map[`string`, Example Object \| Reference Object]	再利用可能なExample Objectsを保持するためのオブジェクト。
リクエストボディ	Map[`string`, Request Body Object \| Reference Object]	再利用可能なリクエストボディオブジェクトを保持するためのオブジェクト。
ヘッダー	Map[`string`, Header Object \| Reference Object]	再利用可能なHeader Objectsを保持するためのオブジェクト。
セキュリティスキーム	Map[`string`, Security Scheme Object \| Reference Object]	再利用可能なSecurity Scheme Objectsを保持するためのオブジェクト。
リンク	Map[`string`, Link Object \| Reference Object]	再利用可能なLink Objectsを保持するためのオブジェクト。
コールバック	Map[`string`, Callback Object \| Reference Object]	再利用可能なCallback Objectsを保持するためのオブジェクト。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

上記のすべての固定フィールドは、正規表現^[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": "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を照合する際には、テンプレート化されていない具体的なパスが、テンプレート化されたパスよりも先に照合されます。同じ階層でもテンプレート化された名前が異なるテンプレートパスは、同一であるため存在してはなりません。曖昧な照合が発生した場合、どちらを使用するかはツールが決定します。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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

  /pets/{petId}
  /pets/mine

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

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

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

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

パスオブジェクトの例

{
  "/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	`文字列`	このパスアイテムの外部定義を許可します。参照される構造はPath Item Objectの形式でなければなりません。定義されたオブジェクトと参照されたオブジェクトの両方にPath Item Objectフィールドが現れる場合、動作は未定義です。
概要	`文字列`	このパス内のすべての操作に適用されることを意図した、オプションの文字列の概要。
説明	`文字列`	このパス内のすべての操作に適用されることを意図した、オプションの文字列の説明。CommonMark構文はリッチテキスト表現に使用されても構いません。
取得	操作オブジェクト	このパスでの GET 操作の定義。
置く	操作オブジェクト	このパスでの PUT 操作の定義。
投稿	操作オブジェクト	このパスでの POST 操作の定義。
削除	操作オブジェクト	このパスでの DELETE 操作の定義。
オプション	操作オブジェクト	このパスでの OPTIONS 操作の定義。
ヘッド	操作オブジェクト	このパスでの HEAD 操作の定義。
パッチ	操作オブジェクト	このパスでの PATCH 操作の定義。
トレース	操作オブジェクト	このパスに対する TRACE 操作の定義。
サーバー	[サーバーオブジェクト]	このパス内のすべての操作にサービスを提供する代替の`server`配列。
パラメーター	[パラメーターオブジェクト \| 参照オブジェクト]	このパスの下で記述されているすべての操作に適用可能なパラメーターのリスト。これらのパラメーターは操作レベルで上書きできますが、そこで削除することはできません。リストには重複するパラメーターを含めてはなりません。一意のパラメーターは名前と場所の組み合わせによって定義されます。このリストは、OpenAPI Objectのcomponents/parametersで定義されているパラメーターにリンクするためにReference Objectを使用できます。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

{
  "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構文はリッチテキスト表現に使用されても構いません。
外部ドキュメント	外部ドキュメントオブジェクト	この操作に関する追加の外部ドキュメント。
operationId	`文字列`	操作を一意に識別するために使用される文字列。このIDは、APIで記述されているすべての操作の中で一意でなければなりません。operationId値は大文字と小文字が区別されます。ツールやライブラリはoperationIdを使用して操作を一意に識別する場合があるため、一般的なプログラミングの命名規則に従うことが推奨されます。
パラメーター	[パラメーターオブジェクト \| 参照オブジェクト]	この操作に適用されるパラメータのリスト。パラメータがPath Itemで既に定義されている場合、新しい定義がそれを上書きしますが、削除することはできません。リストには重複するパラメータを含めてはなりません。一意のパラメータは、名前と場所の組み合わせによって定義されます。リストは、OpenAPI Objectのcomponents/parametersで定義されているパラメータにリンクするためにReference Objectを使用できます。
リクエストボディ	リクエストボディオブジェクト \| 参照オブジェクト	この操作に適用可能なリクエストボディ。`requestBody`は、HTTP 1.1仕様RFC7231がリクエストボディに対するセマンティクスを明示的に定義しているHTTPメソッドでのみサポートされます。HTTP仕様が曖昧な他のケースでは、`requestBody`はコンシューマーによって無視されるものとします。
レスポンス	応答オブジェクト	必須。この操作の実行から返される可能性のあるレスポンスのリスト。
コールバック	Map[`string`, Callback Object \| Reference Object]	親操作に関連するアウトオブバンドコールバックのマップ。キーはCallback Objectの一意の識別子です。マップ内の各値は、APIプロバイダーによって開始される可能性のあるリクエストと期待されるレスポンスを記述するCallback Objectです。
非推奨	`ブール値`	この操作が非推奨であることを宣言します。コンシューマは、宣言された操作の使用を控えるべきです。デフォルト値は`false`です。
セキュリティ	[セキュリティ要件オブジェクト]	この操作で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のセキュリティ要件オブジェクトが含まれます。リクエストを認証するには、セキュリティ要件オブジェクトのいずれか1つを満たすだけで十分です。セキュリティをオプションにするには、空のセキュリティ要件 (`{}`) を配列に含めることができます。この定義は、トップレベルで宣言された`security`を上書きします。トップレベルのセキュリティ宣言を削除するには、空の配列を使用できます。
サーバー	[サーバーオブジェクト]	この操作にサービスを提供するための代替の`server`配列。Path Item Objectまたはルートレベルで代替の`server`オブジェクトが指定されている場合、この値によって上書きされます。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

操作オブジェクトの例

{
  "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の形式でなければなりません。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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

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

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

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

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

パラメーターの場所

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

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

固定フィールド

フィールド名	タイプ	説明
名前	`文字列`	必須。パラメーターの名前。パラメーター名は大文字と小文字が区別されます。 `in`が`"path"`の場合、`name`フィールドはPaths Objectのpathフィールド内に現れるテンプレート式に対応しなければなりません。詳細についてはPath Templatingを参照してください。 `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で定義されている予約文字 `:/?#[]@!$&'()*+,;=` をパーセントエンコーディングなしで含めることをパラメータ値が許可すべきかどうかを決定します。このプロパティは、`query`の`in`値を持つパラメータにのみ適用されます。デフォルト値は`false`です。
スキーマ	スキーマオブジェクト \| 参照オブジェクト	パラメーターに使用される型を定義するスキーマ。
例	任意	パラメーターの潜在的な値の例。例は、指定されたスキーマとエンコードプロパティが存在する場合はそれに一致すべきです。`example`フィールドは`examples`フィールドと相互排他的です。さらに、例を含む`schema`を参照する場合、`example`値はスキーマによって提供される例を上書きします。JSONまたはYAMLで自然に表現できないメディアタイプの例を表現するには、必要に応じてエスケープを伴う文字列値に例を含めることができます。
例	Map[`string`, Example Object \| Reference Object]	パラメータの潜在的な値の例。各例は、パラメータエンコーディングで指定された正しい形式で値を含めるべきです。`examples`フィールドは`example`フィールドと相互排他的です。さらに、例を含む`schema`を参照する場合、`examples`値はスキーマによって提供される例を上書きします。

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

フィールド名	タイプ	説明
コンテンツ	Map[`string`, Media Type Object]	パラメーターの表現を含むマップ。キーはメディアタイプであり、値がそれを記述します。マップにはエントリを1つだけ含めなければなりません。

スタイル値

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

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

スタイル例

colorという名前のパラメーターが次のいずれかの値を持つと仮定します。

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

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

`スタイル`	`爆発する`	`空`	`文字列`	`配列`	`オブジェクト`
マトリックス	偽	;色	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
マトリックス	本当	;色	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
ラベル	偽	.	.青	.青.黒.茶	.R.100.G.200.B.150
ラベル	本当	.	.青	.青.黒.茶	.R=100.G=200.B=150
フォーム	偽	色=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
フォーム	本当	色=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
シンプル	偽	該当なし	青	青、黒、茶	R,100,G,200,B,150
シンプル	本当	該当なし	青	青、黒、茶	R=100,G=200,B=150
スペース区切り	偽	該当なし	該当なし	青%20黒%20茶	R%20100%20G%20200%20B%20150
パイプ区切り	偽	該当なし	該当なし	青\|黒\|茶	R\|100\|G\|200\|B\|150
ディープオブジェクト	本当	該当なし	該当なし	該当なし	color[R]=100&color[G]=200&color[B]=150

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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構文はリッチテキスト表現に使用されても構いません。
コンテンツ	Map[`string`, Media Type Object]	必須。リクエストボディのコンテンツ。キーはメディアタイプまたはメディアタイプレンジであり、値がそれを記述します。複数のキーに一致するリクエストの場合、最も具体的なキーのみが適用されます。例: text/plainはtext/*を上書きします。
必須	`ブール値`	リクエストボディがリクエストで必須かどうかを決定します。デフォルトは`false`です。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

リクエストボディの例

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

{
  "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`値はスキーマによって提供される例を上書きします。
例	Map[`string`, Example Object \| Reference Object]	メディアタイプの例。各例オブジェクトは、メディアタイプと、存在する場合は指定されたスキーマに一致すべきです。`examples`フィールドは`example`フィールドと相互排他的です。さらに、例を含む`schema`を参照する場合、`examples`値はスキーマによって提供される例を上書きします。
エンコーディング	Map[`string`, Encoding Object]	プロパティ名とそのエンコード情報の間のマップ。プロパティ名であるキーは、スキーマ内にプロパティとして存在しなければなりません。エンコーディングオブジェクトは、メディアタイプが`multipart`または`application/x-www-form-urlencoded`の場合にのみ`requestBody`オブジェクトに適用されるものとします。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

メディアタイプの例

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

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型を渡す場合、転送されるコンテンツのセクションを区切るために境界が使用されても構いません。したがって、multipartには次のデフォルトのContent-Typeが定義されています。

プロパティがプリミティブ、またはプリミティブ値の配列である場合、デフォルトの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'

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

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

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

固定フィールド

フィールド名	タイプ	説明
コンテンツタイプ	`文字列`	特定のプロパティをエンコードするためのContent-Type。デフォルト値はプロパティの型に依存します。`string`型で`format`が`binary`の場合は`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`プロパティの詳細についてはParameter Objectを参照してください。動作は`query`パラメータと同じ値を持ち、デフォルト値も含まれます。リクエストボディのメディアタイプが`application/x-www-form-urlencoded`でない場合、このプロパティは無視されるものとします。
展開	`ブール値`	これがtrueの場合、型が`array`または`object`のプロパティ値は、配列の各値、またはマップのキーと値のペアに対して個別のパラメーターを生成します。他の型のプロパティの場合、このプロパティは効果がありません。`style`が`form`の場合、デフォルト値は`true`です。その他のすべてのスタイルでは、デフォルト値は`false`です。リクエストボディのメディアタイプが`application/x-www-form-urlencoded`でない場合、このプロパティは無視されるものとします。
allowReserved	`ブール値`	RFC3986で定義されている予約文字 `:/?#[]@!$&'()*+,;=` をパーセントエンコーディングなしで含めることをパラメータ値が許可すべきかどうかを決定します。デフォルト値は`false`です。リクエストボディのメディアタイプが`application/x-www-form-urlencoded`でない場合、このプロパティは無視されるものとします。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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応答コードに対して宣言されたもの以外の応答のドキュメント。宣言されていない応答をカバーするためにこのフィールドを使用します。Reference Objectは、OpenAPI Objectのcomponents/responsesセクションで定義されている応答にリンクできます。

パターンフィールド

フィールドパターン	タイプ	説明
HTTPステータスコード	レスポンスオブジェクト \| 参照オブジェクト	任意のHTTPステータスコードをプロパティ名として使用できますが、そのHTTPステータスコードの期待される応答を記述するために、コードごとに1つのプロパティのみを使用できます。Reference Objectは、OpenAPI Objectのcomponents/responsesセクションで定義されている応答にリンクできます。このフィールドは、JSONとYAMLの互換性のために引用符で囲まなければなりません（例: "200"）。応答コードの範囲を定義するには、このフィールドに大文字のワイルドカード文字`X`を含めても構いません。たとえば、`2XX`は`[200-299]`のすべての応答コードを表します。許可される範囲定義は、`1XX`、`2XX`、`3XX`、`4XX`、および`5XX`のみです。明示的なコードを使用して応答が定義されている場合、そのコードの範囲定義よりも明示的なコード定義が優先されます。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

成功した操作に対する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が含まれます。

固定フィールド

フィールド名	タイプ	説明
説明	`文字列`	必須。応答の簡単な説明。CommonMark構文はリッチテキスト表現に使用されても構いません。
ヘッダー	Map[`string`, Header Object \| Reference Object]	ヘッダー名をその定義にマッピングします。RFC7230は、ヘッダー名が大文字と小文字を区別しないと規定しています。応答ヘッダーが`"Content-Type"`という名前で定義されている場合、それは無視されるものとします。
コンテンツ	Map[`string`, Media Type Object]	潜在的な応答ペイロードの記述を含むマップ。キーはメディアタイプまたはメディアタイプレンジであり、値がそれを記述します。複数のキーに一致する応答の場合、最も具体的なキーのみが適用されます。例: text/plainはtext/*を上書きします。
リンク	Map[`string`, Link Object \| Reference Object]	応答からたどることができる操作リンクのマップ。マップのキーは、Component Objectsの名前の命名制約に従う、リンクの短い名前です。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

複雑な型の配列の応答

{
  "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プロバイダーによって開始される可能性のある一連のリクエストと、期待される応答を記述するPath Item Objectです。パスアイテムオブジェクトを識別するために使用されるキー値は、ランタイム時に評価され、コールバック操作に使用するURLを識別する式です。

パターンフィールド

フィールドパターン	タイプ	説明
{表現}	パス項目オブジェクト	コールバックリクエストと期待される応答を定義するために使用されるPath Item Object。完全な例が利用可能です。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

キー式

Path Item Objectを識別するキーは、ランタイム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という名前のクエリパラメータがあるとして、さまざまな式がどのように評価されるかを示しています。

式	値
$url	http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	http://clientdomain.com/stillrunning
$request.header.content-Type	application/json
$request.body#/failedUrl	http://clientdomain.com/failed
$request.body#/successUrls/2	http://clientdomain.com/medium
$response.header.Location	http://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

例オブジェクト

固定フィールド

フィールド名	タイプ	説明
概要	`文字列`	例の簡単な説明。
説明	`文字列`	例の詳細な説明。CommonMark構文はリッチテキスト表現に使用されても構いません。
値	任意	埋め込みリテラル例。`value`フィールドと`externalValue`フィールドは相互排他的です。JSONまたはYAMLで自然に表現できないメディアタイプの例を表現するには、必要に応じてエスケープを伴う文字列値に例を含めます。
外部値	`文字列`	リテラル例を指すURL。これは、JSONまたはYAMLドキュメントに簡単に含めることができない例を参照する機能を提供します。`value`フィールドと`externalValue`フィールドは相互排他的です。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

すべての場合において、例の値は関連する値のタイプスキーマと互換性があることが期待されます。ツール実装は、互換性を自動的に検証し、互換性がない場合は例の値の受け入れを拒否することを選択しても構いません。

Example Objectの例

リクエストボディ内

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'

リンクオブジェクト

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

動的リンク（すなわち、応答ペイロード内で提供されるリンク）とは異なり、OASのリンクメカニズムはランタイム応答にリンク情報を必要としません。

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

固定フィールド

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

このオブジェクトはSpecification Extensionsで拡張されても構いません。

リンクされた操作は、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はOperation Objectのオプションフィールド）、参照は相対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メッセージ内でのみ利用可能な情報に基づいて値を定義することを可能にします。このメカニズムはLink ObjectsとCallback Objectsによって使用されます。

ランタイム式は、次の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識別子は大文字と小文字を区別しますが、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は指定してはなりません。対応する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

タグオブジェクト

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

固定フィールド

フィールド名	タイプ	説明
名前	`文字列`	必須。タグの名前。
説明	`文字列`	タグの簡単な説明。CommonMark構文はリッチテキスト表現に使用されても構いません。
外部ドキュメント	外部ドキュメントオブジェクト	このタグの追加の外部ドキュメント。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

タグオブジェクトの例

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

name: pet
description: Pets operations

参照オブジェクト

仕様内の他のコンポーネントを内部的および外部的に参照できるようにするシンプルなオブジェクト。

Reference ObjectはJSON Referenceによって定義され、同じ構造、動作、ルールに従います。

この仕様では、参照解決はJSON Schema仕様ではなくJSON Reference仕様で定義されているとおりに実行されます。

固定フィールド

フィールド名	タイプ	説明
$ref	`文字列`	必須。参照文字列。

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

参照オブジェクトの例

{
	"$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 Wright Draft 00の拡張されたサブセットです。

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

プロパティ

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

タイトル
multipleOf
最大値
exclusiveMaximum
最小値
exclusiveMinimum
maxLength
minLength
パターン（この文字列はEcma-262 Edition 5.1正規表現方言に従って、有効な正規表現であるべきです）
maxItems
minItems
uniqueItems
maxProperties
minProperties
必須
列挙型

以下のプロパティはJSON Schemaの定義から採用されていますが、その定義はOpenAPI Specificationに合わせて調整されています。

type - 値は文字列でなければなりません。配列による複数型はサポートされていません。
allOf - インラインまたは参照スキーマは、標準のJSON Schemaではなく、Schema Objectでなければなりません。
oneOf - インラインまたは参照スキーマは、標準のJSON Schemaではなく、Schema Objectでなければなりません。
anyOf - インラインまたは参照スキーマは、標準のJSON Schemaではなく、Schema Objectでなければなりません。
not - インラインまたは参照スキーマは、標準のJSON Schemaではなく、Schema Objectでなければなりません。
items - 値はオブジェクトでなければならず、配列であってはなりません。インラインまたは参照スキーマは、標準のJSON Schemaではなく、Schema Objectでなければなりません。typeがarrayの場合、itemsは存在しなければなりません。
properties - プロパティ定義は、標準のJSONスキーマではなく（インラインまたは参照されている）スキーマオブジェクトでなければなりません。
additionalProperties - 値はブール値またはオブジェクトのいずれかです。インラインまたは参照スキーマは、標準のJSONスキーマではなくSchema Objectでなければなりません。JSONスキーマと一貫して、additionalPropertiesのデフォルトはtrueです。
description - CommonMark構文はリッチテキスト表現に使用されても構いません。
format - 詳細についてはData Type Formatsを参照してください。JSON Schemaで定義されたフォーマットに依拠しつつ、OASはいくつかの追加の事前定義フォーマットを提供します。
default - デフォルト値は、入力の消費者が値が提供されない場合にスキーマの値として想定するものを表します。JSON Schemaとは異なり、値は同じレベルで定義されたSchema Objectの定義された型に準拠しなければなりません。例えば、typeがstringの場合、defaultは"foo"であっても構いませんが、1であってはなりません。

あるいは、Schema Objectが使用できる場合、いつでもReference Objectをその代わりに使用できます。これにより、定義をインラインで定義する代わりに参照できます。

JSON Schema仕様で定義されているがここに記載されていない追加のプロパティは、厳密にサポートされていません。

JSON Schemaのサブセットフィールド以外に、以下のフィールドはスキーマのさらなるドキュメントのために使用されても構いません。

固定フィールド

フィールド名	タイプ	説明
null許容	`ブール値`	`true`値は、`type`が同じSchema Object内で明示的に定義されている場合に限り、許可される型に`"null"`を追加します。その他のSchema Objectの制約は定義された動作を維持するため、`null`を値として使用することを許可しない場合があります。`false`値は、指定されたまたはデフォルトの`type`を変更しません。デフォルト値は`false`です。
差別化要因	Discriminator オブジェクト	多態性をサポートします。discriminatorは、ペイロード記述を満たす可能性のある他のスキーマと区別するために使用されるオブジェクト名です。詳細についてはComposition and Inheritanceを参照してください。
読み取り専用	`ブール値`	スキーマ`"properties"`定義にのみ関連します。プロパティを「読み取り専用」として宣言します。これは、応答の一部として送信されてもよいが、要求の一部として送信すべきではないことを意味します。プロパティが`readOnly`が`true`とマークされ、`required`リストにある場合、`required`は応答にのみ影響します。プロパティは`readOnly`と`writeOnly`の両方が`true`とマークされてはなりません。デフォルト値は`false`です。
書き込み専用	`ブール値`	スキーマ`"properties"`定義にのみ関連します。プロパティを「書き込み専用」として宣言します。したがって、要求の一部として送信されてもよいが、応答の一部として送信すべきではありません。プロパティが`writeOnly`が`true`とマークされ、`required`リストにある場合、`required`は要求にのみ影響します。プロパティは`readOnly`と`writeOnly`の両方が`true`とマークされてはなりません。デフォルト値は`false`です。
xml	XMLオブジェクト	これはプロパティスキーマでのみ使用しても構いません。ルートスキーマには影響しません。このプロパティのXML表現を記述するための追加メタデータを追加します。
外部ドキュメント	外部ドキュメントオブジェクト	このスキーマに関する追加の外部ドキュメント。
例	任意	このスキーマのインスタンスの例を含めるための自由形式のプロパティ。JSONまたはYAMLで自然に表現できない例を表現するには、必要に応じてエスケープを伴う文字列値に例を含めることができます。
非推奨	`ブール値`	スキーマが非推奨であり、使用から移行すべきであることを指定します。デフォルト値は`false`です。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

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

コンポジションはモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。多態性をサポートするために、OpenAPI Specificationはdiscriminatorフィールドを追加します。使用される場合、discriminatorは、ペイロード記述を満たす可能性のある他のスキーマを区別するために使用されるプロパティの名前となります。したがって、discriminatorフィールドは必須フィールドでなければなりません。継承インスタンスのdiscriminatorの値を定義するには2つの方法があります。

スキーマ名を使用します。
新しい値でプロパティを上書きすることにより、スキーマ名を上書きします。新しい値が存在する場合、それがスキーマ名よりも優先されます。したがって、IDが与えられていないインラインスキーマ定義は、多態性では使用できません。

XMLモデリング

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

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

プリミティブサンプル

{
  "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は、ペイロード記述を満たす可能性のある他のスキーマと区別するために使用されるスキーマ内の特定のオブジェクトです。discriminatorは、それに紐付けられた値に基づいて代替スキーマを仕様のコンシューマに知らせるために使用されます。

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

固定フィールド

フィールド名	タイプ	説明
プロパティ名	`文字列`	必須。discriminator値を保持するペイロード内のプロパティ名。
マッピング	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'

ここでは、discriminatorの値であるdogは、デフォルト（暗黙的）の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"
}

mappings要素の定義によりDogにマッピングされます。

XMLオブジェクト

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

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

固定フィールド

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

このオブジェクトはSpecification Extensionsで拡張されても構いません。

XMLオブジェクトの例

XMLオブジェクト定義の例は、Schema Objectのプロパティ定義内に、その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キー（ヘッダー、Cookieパラメーター、またはクエリパラメーターのいずれか）、RFC6749で定義されているOAuth2の一般的なフロー（implicit、password、client credentials、authorization code）、およびOpenID Connect Discoveryです。

固定フィールド

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

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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

基本認証の例

{
  "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` と呼ばれていました。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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 セキュリティスキームで利用可能なスコープ。スコープ名とそれに対する短い説明の間のマップ。マップは空であっても構いません。

このオブジェクトはSpecification Extensionsで拡張されても構いません。

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つだけを満たせば十分です。

パターンフィールド

フィールドパターン	タイプ	説明
{名前}	[`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 Specification 3.0.3 のパッチリリース
3.0.2	2018-10-08	OpenAPI Specification 3.0.2 のパッチリリース
3.0.1	2017-12-06	OpenAPI Specification 3.0.1 のパッチリリース
3.0.0	2017-07-26	OpenAPI Specification 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.0.3

はじめに

目次

定義

OpenAPIドキュメント

パスのテンプレート化

メディアタイプ

HTTP ステータスコード

仕様

バージョン

フォーマット

ドキュメント構造

データ型

リッチテキスト書式設定

URL内の相対参照

スキーマ

OpenAPI オブジェクト

固定フィールド

情報オブジェクト

固定フィールド

情報オブジェクトの例

連絡先オブジェクト

固定フィールド

連絡先オブジェクトの例

ライセンスオブジェクト

固定フィールド

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

サーバーオブジェクト

固定フィールド

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

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

固定フィールド

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

固定フィールド

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

パスオブジェクト

パターンフィールド

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

パスオブジェクトの例

パス項目オブジェクト

固定フィールド

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

操作オブジェクト

固定フィールド

操作オブジェクトの例

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

固定フィールド

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

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

パラメーターの場所

固定フィールド

スタイル値

スタイル例

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

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

固定フィールド

リクエストボディの例

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

固定フィールド

メディアタイプの例

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

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

multipartコンテンツの特別な考慮事項

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

固定フィールド

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

応答オブジェクト

固定フィールド

パターンフィールド

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

レスポンスオブジェクト

固定フィールド

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

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

パターンフィールド

キー式

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

例オブジェクト

固定フィールド

`multipart`コンテンツの特別な考慮事項