External Documentationオブジェクト

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

固定フィールド

フィールド名	タイプ	説明
説明	`string`	ターゲットドキュメントの説明。CommonMark 構文はリッチテキスト表現に使用できます (MAY)。
URL	`string`	必須。ターゲットドキュメントの URL。これは URL の形式でなければなりません。

このオブジェクトは、仕様拡張機能を使用して拡張できます。

External Documentationの例

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

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

Parameterオブジェクト

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

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

パラメータの場所

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

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

固定フィールド

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

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

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

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

フィールド名	タイプ	説明
コンテンツ	Map[ `string`,メディアタイプオブジェクト]	パラメータの表現を含むマップ。キーはメディアタイプであり、値はそれを説明します。マップにはエントリを 1 つだけ含める必要があります。

スタイル値

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

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

スタイルの例

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

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

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

`style`	`explode`	`empty`	`string`	`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

External Documentationオブジェクト

固定フィールド​

External Documentationの例​

Parameterオブジェクト​

パラメータの場所​

固定フィールド​

スタイル値​

スタイルの例​

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

固定フィールド

External Documentationの例

Parameterオブジェクト

パラメータの場所

固定フィールド

スタイル値

スタイルの例

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