説明
components.requestBodies に定義した本文は、操作の requestBody から参照して使用します。共通定義だけでは、その操作が本文を受け取るという説明にはなりません。
想定される影響
操作の入力形式と共通定義の関係が分かりにくくなり、変更時に不要な確認が増える可能性があります。
対処方法
本文を受け取る操作から必要な定義を参照し、コンテンツタイプとスキーマを実際のリクエストに合わせてください。外部文書でも使われていない不要な定義だけを削除してください。
例
次の POST の例では、操作の requestBody から MyObjectBody を参照しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"requestBodies": {
"MyObjectBody": {
"description": "A JSON object containing my object information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
},
"requestBody": {
"$ref": "#/components/requestBodies/MyObjectBody"
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"requestBodies": {
"MyObjectBody": {
"description": "A JSON object containing my object information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}