Request Body Object in OpenAPI
The request body is used to describe the HTTP body of the request for
operations. Not all operations require a request body, but when they do, the
request body is defined in the requestBody field of the operation object.
Request Body Object
Here’s how the requestBody object is structured:
Request Body Object Fields
Required vs optional
Request bodies are optional by default in OpenAPI, so adding the requestBody
property does not mean it expects the HTTP request to actually be present. It
means it can be present.
This can be changed by setting the required property to true, but it is
often forgotten and lots of tooling will remind you to add a required property,
even if its set to required: false, just to make sure there is nothing spooky
or unexpected happening.
Getting this right is not just important for API documentation, but for generated SDKs that should know whether or not to throw errors, and data validations libraries/middlewares which should know whether or not to reject an invalid request.
When should a request body be optional?
Not all that often, but it can be useful for things like PATCH requests
where no changes are happening but you want to “touch” the resource to update the updatedAt timestamp.
To support this use case, the requestBody can be set to be optional.
Sometimes an API will set a request body for a DELETE request, but this is less common and recommended against in both RFC9110: HTTP Semantics and the OpenAPI specification.
Still, OpenAPI begrudgingly allows DELETE to describe a requestBody knowing
that some legacy APIs will have done this, and some tooling will even support it.
It’s important to describe the API correctly, regardless of which best practices it has gone against, but whenever possible channel the feedback to the developers and see if those mistakes can be avoided in the future.
Encoding Object
Only applicable to requestBody where the media type is multipart or application/x-www-form-urlencoded. An encoding object describes the encoding of a single property in the request schema.
Encoding Object Fields
anyOf and oneOf
Sometimes a request body could contain multiple different data structures:
Learn more about this concept in the schema composition guide.
Last updated on