OpenAPI Request Bodies — Defining Input Data for POST and PUT
In this tutorial, you will learn about OpenAPI Request Bodies. We cover key concepts, practical examples, and best practices to help you master this topic.
OpenAPI request bodies define the data that clients send to the API for POST, PUT, and PATCH operations, specifying content types, schema structures, and whether the body is required.
In this tutorial, you will learn how to define request bodies in OpenAPI, handle multiple content types, use $ref for schema reuse, and document request body examples clearly.
What You'll Learn
You will learn how to define request bodies for write operations, handle different content types like JSON and form data, create reusable request body definitions, and provide clear examples for each request body.
Why It Matters
Request bodies are the most complex part of API documentation. Clients need to know exactly what data to send, in what format, and which fields are required. Well-documented request bodies reduce validation errors and integration friction.
Real-World Use
DodaTech APIs use standardized request body schemas across all services. The CreateUser request body is defined once and used by both the web app and the mobile API Gateway, ensuring consistent validation and documentation.
flowchart LR A[Client Request] --> B[Request Body] B --> C[Content Type] B --> D[Schema Validation] B --> E[Required Fields] D --> F[Server Processing] A:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Basic Request Body Definition
Every request body specifies the content type and schema.
paths:
/users:
post:
summary: Create a new user
operationId: createUser
requestBody:
description: User creation payload
required: true
content:
application/json:
schema:
type: object
required:
- name
- email
properties:
name:
type: string
description: Full name of the user
example: "Alice Johnson"
email:
type: string
format: email
description: Email address for the account
example: "alice@example.com"
password:
type: string
format: password
minLength: 8
description: Account password
role:
type: string
enum: [admin, member, viewer]
default: member
description: User role assignment
responses:
"201":
description: User created successfully
Multiple Content Types
Some endpoints accept multiple content types.
/users/import:
post:
summary: Import users from CSV
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/UserImport"
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: CSV file with user data
options:
type: object
properties:
updateExisting:
type: boolean
default: false
skipDuplicates:
type: boolean
default: true
required: true
responses:
"200":
description: Import results
Using $ref for Request Bodies
For reusability, define request bodies in components.
components:
requestBodies:
CreateUser:
description: Payload for creating a new user account
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserRequest"
UpdateUser:
description: Payload for updating an existing user
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateUserRequest"
paths:
/users:
post:
summary: Create a new user
requestBody:
$ref: "#/components/requestBodies/CreateUser"
responses:
"201":
description: User created
/users/{userId}:
patch:
summary: Update a user
requestBody:
$ref: "#/components/requestBodies/UpdateUser"
responses:
"200":
description: User updated
Optional Request Bodies
Some operations have optional request bodies.
/users/search:
post:
summary: Search users with advanced filters
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: Full-text search query
filters:
type: object
properties:
role:
type: string
status:
type: string
createdAfter:
type: string
format: date
sort:
type: string
default: "-created_at"
responses:
"200":
description: Search results
Request Body Examples
Provide multiple examples for different scenarios.
/users:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserRequest"
examples:
basic:
summary: Minimal user creation
value:
name: "Alice Johnson"
email: "alice@example.com"
password: "securePass123"
admin:
summary: Admin user creation
value:
name: "Bob Admin"
email: "bob@dodatech.com"
password: "adminPass456"
role: "admin"
bulk:
summary: Bulk import format
value:
users:
- name: "Charlie"
email: "charlie@example.com"
- name: "Diana"
email: "diana@example.com"
Common Mistakes
Missing required flag — Not specifying
required: trueorrequired: false. Clients do not know if the body is mandatory. Default is false, so always be explicit.No schema for request body — Defining content without a schema. The schema is what generates documentation and enables validation. Always include a schema.
Single content type when multiple are needed — Only supporting JSON when form data or file uploads are needed. Consider all input formats your API supports.
No examples for complex bodies — Leaving developers to guess the format of nested objects. Provide examples for every request body, especially complex ones.
Inconsistent field naming — Using different field names in request and response for the same data. Keep request and response field names consistent.
Practice Questions
- How do you mark a request body as required in OpenAPI?
- How can you support both JSON and form data for the same endpoint?
- What is the purpose of the examples field in a request body?
- How do you make request body definitions reusable?
- When would you use an optional request body?
Challenge
Design request bodies for a document management API. Create schemas for creating a document (title, content, tags, category), uploading a file (multipart with metadata), updating a document (partial update with optional fields), searching documents (complex filter object), and bulk operations (create/update/delete multiple documents at once).
FAQ
Mini Project
Create a complete request body schema set for an e-commerce checkout API. Define request bodies for adding items to cart, updating cart quantities, applying coupons, setting shipping address, selecting payment method, and placing the order. Include examples for each.
What's Next
In the next lesson, you will learn how to define responses in OpenAPI, including status codes, content types, schema references, and headers.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro