Describing Request Body
Request bodies are typically used with “create” and “update” operations (POST, PUT, PATCH). For example, when creating a resource using POST or PUT, the request body usually contains the representation of the resource to be created. OpenAPI 3.0 provides the requestBody
keyword to describe request bodies.
Differences From OpenAPI 2.0
If you used OpenAPI 2.0 before, here is a summary of changes to help you get started with OpenAPI 3.0:
- Body and form parameters are replaced with
requestBody
. - Operations can now consume both form data and other media types such as JSON.
- The
consumes
array is replaced with therequestBody.content
map which maps the media types to their schemas. - Schemas can vary by media type.
anyOf
andoneOf
can be used to specify alternate schemas.- Form data can now contain objects, and you can specify the serialization strategy for objects and arrays.
- GET, DELETE and HEAD are no longer allowed to have request body because it does not have defined semantics as per RFC 7231.
requestBody, content and Media Types
Unlike OpenAPI 2.0, where the request body was defined using body
and formData
parameters, OpenAPI 3.0 uses the requestBody
keyword to distinguish the payload from parameters (such as query string). The requestBody
is more flexible in that it lets you consume different media types, such as JSON, XML, form data, plain text, and others, and use different schemas for different media types. requestBody
consists of the content
object, an optional Markdown-formatted description
, and an optional required
flag (false
by default). content
lists the media types consumed by the operation (such as application/json
) and specifies the schema
for each media type. Request bodies are optional by default. To mark the body as required, use required: true
.
1paths:2 /pets:3 post:4 summary: Add a new pet5
6 requestBody:7 description: Optional description in *Markdown*8 required: true9 content:10 application/json:11 schema:12 $ref: "#/components/schemas/Pet"13 application/xml:14 schema:15 $ref: "#/components/schemas/Pet"16 application/x-www-form-urlencoded:17 schema:18 $ref: "#/components/schemas/PetForm"19 text/plain:20 schema:21 type: string22
23 responses:24 "201":25 description: Created
content
allows wildcard media types. For example, image/*
represents all image types; */*
represents all types and is functionally equivalent to application/octet-stream
. Specific media types have preference over wildcard media types when interpreting the spec, for example, image/png
> image/*
> */*
.
1paths:2 /avatar:3 put:4 summary: Upload an avatar5 requestBody:6 content:7 image/*: # Can be image/png, image/svg, image/gif, etc.8 schema:9 type: string10 format: binary
anyOf, oneOf
OpenAPI 3.0 supports anyOf
and oneOf
, so you can specify alternate schemas for the request body:
1requestBody:2 description: A JSON object containing pet information3 content:4 application/json:5 schema:6 oneOf:7 - $ref: "#/components/schemas/Cat"8 - $ref: "#/components/schemas/Dog"9 - $ref: "#/components/schemas/Hamster"
File Upload
To learn how to describe file upload, see File Upload and Multipart Requests.
Request Body Examples
The request body can have an example
or multiple examples
. example
and examples
are properties of the requestBody.content.<media-type>
object. If provided, these examples override the examples provided by the schema. This is handy, for example, if the request and response use the same schema but you want to have different examples. example
allows a single inline example:
1requestBody:2 content:3 application/json:4 schema:5 $ref: "#/components/schemas/Pet"6 example:7 name: Fluffy8 petType: dog
The examples
(plural) are more flexible – you can have an inline example, a $ref
reference, or point to an external URL containing the payload example. Each example can also have optional summary
and description
for documentation purposes.
1requestBody:2 content:3 application/json:4 schema:5 $ref: '#/components/schemas/Pet'6 examples:7
8 dog: # <--- example name9 summary: An example of a dog10 value:11 # vv Actual payload goes here vv12 name: Fluffy13 petType: dog14
15 cat: # <--- example name16 summary: An example of a cat17 externalValue: http://api.example.com/examples/cat.json # cat.json contains {"name": "Tiger", "petType": "cat"}18
19 hamster: # <--- example name20 $ref: '#/components/examples/hamster'21
22 components:23 examples:24 hamster: # <--- example name25 summary: An example of a hamster26 value:27 # vv Actual payload goes here vv28 name: Ginger29 petType: hamster
See Adding Examples for more information.
Reusable Bodies
You can put the request body definitions in the global components.requestBodies
section and $ref
them elsewhere. This is handy if multiple operations have the same request body – this way you can reuse the same definition easily.
1paths:2 /pets:3 post:4 summary: Add a new pet5 requestBody:6 $ref: '#/components/requestBodies/PetBody'7
8 /pets/{petId}9 put:10 summary: Update a pet11 parameters: [ ... ]12 requestBody:13 $ref: '#/components/requestBodies/PetBody'14
15components:16 requestBodies:17 PetBody:18 description: A JSON object containing pet information19 required: true20 content:21 application/json:22 schema:23 $ref: '#/components/schemas/Pet'
Form Data
The term “form data” is used for the media types application/x-www-form-urlencoded
and multipart/form-data
, which are commonly used to submit HTML forms.
application/x-www-form-urlencoded
is used to send simple ASCII text data askey=value
pairs. The payload format is similar to query parameters.multipart/form-data
allows submitting binary data as well as multiple media types in a single message (for example, image and JSON). Each form field has its own section in the payload with internal HTTP headers.multipart
requests are commonly used for file uploads.
To illustrate form data, consider an HTML POST form:
1<form action="http://example.com/survey" method="post">2 <input type="text" name="name" />3 <input type="number" name="fav_number" />4 <input type="submit" />5</form>
This form POSTs data to the form’s endpoint:
1POST /survey HTTP/1.12Host: example.com3Content-Type: application/x-www-form-urlencoded4Content-Length: 285
6name=Amy+Smith&fav_number=42
In OpenAPI 3.0, form data is modelled using a type: object
schema where the object properties represent the form fields:
1paths:2 /survey:3 post:4 requestBody:5 required: true6 content:7 application/x-www-form-urlencoded:8 schema:9 type: object10 properties:11 name: # <!--- form field name12 type: string13 fav_number: # <!--- form field name14 type: integer15 required:16 - name17 - email
Form fields can contain primitives values, arrays and objects. By default, arrays are serialized as array_name=value1&array_name=value2
and objects as prop1=value1&prop=value2
, but you can use other serialization strategies as defined by the OpenAPI 3.0 Specification. The serialization strategy is specified in the encoding
section like so:
1requestBody:2 content:3 application/x-www-form-urlencoded:4 schema:5 type: object6 properties:7 color:8 type: array9 items:10 type: string11 encoding:12 color: # color=red,green,blue13 style: form14 explode: false
By default, reserved characters :/?#[]@!$&'()*+,;=
in form field values within application/x-www-form-urlencoded
bodies are percent-encoded when sent. To allow these characters to be sent as is, use the allowReserved
keyword like so:
1requestBody:2 content:3 application/x-www-form-urlencoded:4 schema:5 type: object6 properties:7 foo:8 type: string9 bar:10 type: string11 baz:12 type: string13 encoding:14 # Don't percent-encode reserved characters in the values of "bar" and "baz" fields15 bar:16 allowReserved: true17 baz:18 allowReserved: true
Arbitrary key=value
pairs can be modelled using a free-form schema:
1requestBody:2 content:3 application/x-www-form-urlencoded:4 schema:5 type: object6 additionalProperties: true # this line is optional
Complex Serialization in Form Data
The serialization rules provided by the style
and explode
keywords only have defined behavior for arrays of primitives and objects with primitive properties. For more complex scenarios, such as nested arrays or JSON in form data, you need to use the contentType
keyword to specify the media type for encoding the value of a complex field. Consider Slack incoming webhooks for an example. A message can be sent directly as JSON, or the JSON data can be sent inside a form field named payload
like so (before URL-encoding is applied):
1payload={"text":"Swagger is awesome"}
This can be described as:
1openapi: 3.0.02info:3 version: 1.0.04 title: Slack Incoming Webhook5externalDocs:6 url: https://api.slack.com/incoming-webhooks7
8servers:9 - url: https://hooks.slack.com10
11paths:12 /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:13 post:14 summary: Post a message to Slack15 requestBody:16 content:17 application/json:18 schema:19 $ref: "#/components/schemas/Message"20
21 application/x-www-form-urlencoded:22 schema:23 type: object24 properties:25 payload: # <--- form field that contains the JSON message26 $ref: "#/components/schemas/Message"27 encoding:28 payload:29 contentType: application/json30
31 responses:32 "200":33 description: OK34
35components:36 schemas:37 Message:38 title: A Slack message39 type: object40 properties:41 text:42 type: string43 description: Message text44 required:45 - text
References
Did not find what you were looking for? Ask the community
Found a mistake? Let us know