Description
A $ref in requestBody must point to a Request Body Object. A schema alone cannot replace this object, which describes both the media type and the body structure.
Potential impact
Documentation may omit the request body format, or clients may construct incorrect requests.
Remediation
Reference shared request bodies through #/components/requestBodies/... and place their schemas inside content. Valid external Request Body Objects can also be referenced.
Examples
These POST examples correct the List reference path from schemas to requestBodies.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"components": {
"requestBodies": {
"List": {
"description": "id of api version",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
}
}
}
}
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"requestBody": {
"$ref": "#/components/schemas/List"
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"components": {
"requestBodies": {
"List": {
"description": "id of api version",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "integer"
}
}
}
}
}
}
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"requestBody": {
"$ref": "#/components/requestBodies/List"
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}