説明
OpenAPI 3.0 の Parameter オブジェクトでは、content に含められるメディアタイプの項目は一つだけです。application/json と application/xml を同時に指定するなど、複数の項目を含めると Parameter オブジェクトの形式に違反します。
想定される影響
- 検証で仕様書が拒否されたり、クライアント生成が失敗したりする場合があります。
- API 利用者がパラメーター値をどの形式で送るべきか迷う可能性があります。
対処方法
パラメーターの content には実際に使用するメディアタイプを一つだけ残し、そのスキーマと例を確認してください。同じ Parameter オブジェクトで schema と content を同時に指定しないでください。複数のリクエスト本文の形式が必要なら、その本文の契約を別途設計してください。
例
操作レベルとパスレベルのパラメーターで、メディアタイプが二つある場合と一つの場合を比較しています。参照する User スキーマと外部の例のファイルは別途用意してください。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/user/{id}": {
"parameters": [
{
"description": "ID of the API version",
"required": true,
"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"
}
}
}
},
"name": "id",
"in": "path"
}
]
},
"/{id}": {
"get": {
"summary": "List API versions",
"parameters": [
{
"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"
}
}
}
},
"name": "id",
"in": "path",
"description": "ID of the API version",
"required": true
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"rel": "self",
"href": "http://127.0.0.1:8774/v2/"
}
],
"status": "CURRENT"
}
]
}
}
}
}
},
"description": "200 response"
}
},
"operationId": "listVersionsv2"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/user/{id}": {
"parameters": [
{
"description": "ID of the API version",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user": {
"summary": "User Example",
"externalValue": "http://foo.bar/examples/user-example.json"
}
}
}
},
"name": "id",
"in": "path"
}
]
},
"/{id}": {
"get": {
"summary": "List API versions",
"parameters": [
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user": {
"summary": "User Example",
"externalValue": "http://foo.bar/examples/user-example.json"
}
}
}
},
"name": "id",
"in": "path",
"description": "ID of the API version",
"required": true
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"rel": "self",
"href": "http://127.0.0.1:8774/v2/"
}
],
"status": "CURRENT"
}
]
}
}
}
}
},
"description": "200 response"
}
},
"operationId": "listVersionsv2"
}
}
}
}
変更後は各 content に application/json だけを残しています。パスに対応する id を含め、content と併用できない別の schema フィールドを削除しています。