説明
OpenAPI 3.0 では、components.requestBodies のリクエスト本文の定義を $ref で再利用できます。参照先がないと、文書ツールがリクエストのメディアタイプやデータ構造を解釈できない場合があります。
想定される影響
- API 利用者がリクエスト本文の形式やフィールドを誤解する可能性があります。
- 参照エラーによりクライアント生成や仕様書の検証が失敗する場合があります。
対処方法
リクエスト本文の $ref を、実在する Request Body オブジェクトに接続してください。ローカル参照は components.requestBodies の名前と一致させ、本文の content とスキーマ参照も確認してください。変更後に実際の要求形式と文書が一致するか検証してください。
例
POST リクエストで再利用する JSON 本文の比較です。最初の例の MyWrongObjectBody は定義されていません。
変更前
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/MyWrongObjectBody"
}
}
}
},
"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"
}
}
}
}
}
}
}
変更後は MyObjectBody を参照し、その本文は MyObject スキーマで JSON の構造を説明しています。応答のスキーマは別途、応答の content 内に配置しています。