OpenAPI Request Body — Defining Request Payloads with Content Types

In this tutorial, you will learn about OpenAPI Request Body. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI request body defines the payload that clients send to API endpoints, specifying supported content types, schema validation rules, and optionality.

What You'll Learn

• Defining request bodies with content types
• Multiple content type support (JSON, XML, form data)
• File upload handling with multipart encoding

Why It Matters

Accurate request body definitions prevent integration errors. They also enable automatic request validation and client Code Generation.

Code Examples

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - email
        properties:
          name:
            type: string
            example: Alice
          email:
            type: string
            format: email
            example: alice@example.com
          age:
            type: integer
            minimum: 0

# Multiple content types
requestBody:
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/User"
    application/xml:
      schema:
        $ref: "#/components/schemas/User"
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          email:
            type: string

# File upload
requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            format: binary
          description:
            type: string

# Validating request body from OpenAPI
from jsonschema import validate

schema = spec['paths']['/users']['post']['requestBody']['content']['application/json']['schema']

# Validate incoming request
request_data = {"name": "Alice", "email": "alice@example.com"}
validate(instance=request_data, schema=schema)
print("Request body is valid")

Common Mistakes

1. Missing Required Fields in Schema

Always list required fields explicitly in the schema's required array.

2. Not Handling Optional Fields

Document optional fields with descriptions and defaults.

3. Only Supporting application/json

Support form-encoded for simple data and multipart for file uploads.

4. No Example Values

Examples help developers understand the expected format.

5. Forgetting nullable Fields

Mark fields that can be null with nullable: true.

Practice Questions

1. How do you make a request body required?
2. How do you support multiple content types?
3. What schema format is used for file uploads?
4. How do you list required fields in the request body?
5. What is the purpose of the example field?

Answers:

1. Set required: true on the requestBody object.
2. List each content type under the content map.
3. multipart/form-data with format: binary.
4. In the schema's required array.
5. To show developers a realistic example of the expected data.

Challenge: Define the request body for a multi-part form that accepts a user's avatar image and profile data (name, bio, website).

FAQ