Skip to content

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 the requestBody.content map which maps the media types to their schemas.
  • Schemas can vary by media type.
  • anyOf and oneOf 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.

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5


6
      requestBody:
7
        description: Optional description in *Markdown*
8
        required: true
9
        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: string
22


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/* > */*.

1
paths:
2
  /avatar:
3
    put:
4
      summary: Upload an avatar
5
      requestBody:
6
        content:
7
          image/*: # Can be image/png, image/svg, image/gif, etc.
8
            schema:
9
              type: string
10
              format: binary

anyOf, oneOf

OpenAPI 3.0 supports anyOf and oneOf, so you can specify alternate schemas for the request body:

1
requestBody:
2
  description: A JSON object containing pet information
3
  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:

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: "#/components/schemas/Pet"
6
      example:
7
        name: Fluffy
8
        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.

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: '#/components/schemas/Pet'
6
      examples:
7


8
        dog:  # <--- example name
9
          summary: An example of a dog
10
          value:
11
            # vv Actual payload goes here vv
12
            name: Fluffy
13
            petType: dog
14


15
        cat:  # <--- example name
16
          summary: An example of a cat
17
          externalValue: http://api.example.com/examples/cat.json   # cat.json contains {"name": "Tiger", "petType": "cat"}
18


19
        hamster:  # <--- example name
20
          $ref: '#/components/examples/hamster'
21


22
  components:
23
    examples:
24
      hamster:  # <--- example name
25
        summary: An example of a hamster
26
        value:
27
          # vv Actual payload goes here vv
28
          name: Ginger
29
          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.

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5
      requestBody:
6
        $ref: '#/components/requestBodies/PetBody'
7


8
  /pets/{petId}
9
    put:
10
      summary: Update a pet
11
      parameters: [ ... ]
12
      requestBody:
13
        $ref: '#/components/requestBodies/PetBody'
14


15
components:
16
  requestBodies:
17
    PetBody:
18
      description: A JSON object containing pet information
19
      required: true
20
      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 as key=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:

1
POST /survey HTTP/1.1
2
Host: example.com
3
Content-Type: application/x-www-form-urlencoded
4
Content-Length: 28
5


6
name=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:

1
paths:
2
  /survey:
3
    post:
4
      requestBody:
5
        required: true
6
        content:
7
          application/x-www-form-urlencoded:
8
            schema:
9
              type: object
10
              properties:
11
                name: # <!--- form field name
12
                  type: string
13
                fav_number: # <!--- form field name
14
                  type: integer
15
              required:
16
                - name
17
                - 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:

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          color:
8
            type: array
9
            items:
10
              type: string
11
      encoding:
12
        color: # color=red,green,blue
13
          style: form
14
          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:

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          foo:
8
            type: string
9
          bar:
10
            type: string
11
          baz:
12
            type: string
13
      encoding:
14
        # Don't percent-encode reserved characters in the values of "bar" and "baz" fields
15
        bar:
16
          allowReserved: true
17
        baz:
18
          allowReserved: true

Arbitrary key=value pairs can be modelled using a free-form schema:

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        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):

1
payload={"text":"Swagger is awesome"}

This can be described as:

1
openapi: 3.0.4
2
info:
3
  version: 1.0.0
4
  title: Slack Incoming Webhook
5
externalDocs:
6
  url: https://api.slack.com/incoming-webhooks
7


8
servers:
9
  - url: https://hooks.slack.com
10


11
paths:
12
  /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:
13
    post:
14
      summary: Post a message to Slack
15
      requestBody:
16
        content:
17
          application/json:
18
            schema:
19
              $ref: "#/components/schemas/Message"
20


21
          application/x-www-form-urlencoded:
22
            schema:
23
              type: object
24
              properties:
25
                payload: # <--- form field that contains the JSON message
26
                  $ref: "#/components/schemas/Message"
27
            encoding:
28
              payload:
29
                contentType: application/json
30


31
      responses:
32
        "200":
33
          description: OK
34


35
components:
36
  schemas:
37
    Message:
38
      title: A Slack message
39
      type: object
40
      properties:
41
        text:
42
          type: string
43
          description: Message text
44
      required:
45
        - text

References

RequestBody Object

MediaType Object

Did not find what you were looking for? Ask the community
Found a mistake? Let us know