Request Body in OpenAPI — Defining Input for Write Operations
In this tutorial, you will learn about Request Body in OpenAPI. We cover key concepts, practical examples, and best practices to help you master this topic.
The request body object in OpenAPI describes the data that clients send to the API for POST, PUT, and PATCH operations, specifying content types, schema structure, and required status.
In this tutorial, you will learn how to define request bodies, handle multiple content types, use $ref for reusability, and provide comprehensive examples.
What You'll Learn
You will learn the structure of the request body object, how to define content types and schemas, how to make request bodies reusable, and how to provide multiple examples.
flowchart LR A[Request Body] --> B[Content Type] A --> C[Schema] A --> D[Required Flag] A --> E[Examples] B:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Basic Request Body
Every request body specifies the content type and schema:
paths:
/users:
post:
requestBody:
description: Payload for creating a new user
required: true
content:
application/json:
schema:
type: object
required:
- name
- email
properties:
name:
type: string
example: "Alice Johnson"
email:
type: string
format: email
example: "alice@example.com"
password:
type: string
format: password
minLength: 8
role:
type: string
enum: [admin, member, viewer]
default: member
Multiple Content Types
Some endpoints accept multiple input formats:
/documents:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateDocument"
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: Document file
title:
type: string
description: Document title
tags:
type: array
items:
type: string
Reusable Request Bodies
Define request bodies in components:
components:
requestBodies:
CreateUser:
description: Payload for user creation
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserRequest"
UpdateUser:
description: Payload for user update
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateUserRequest"
Request Body Examples
Provide multiple named examples:
/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"
Common Mistakes
Missing required flag — Not specifying if the body is required. Be explicit: write operations typically require it.
No schema — Defining content without a schema. Schemas generate documentation and enable validation.
Single content type when multiple needed — Only supporting JSON when file uploads are needed.
No examples — Leaving developers to guess the format. Always provide examples.
Inconsistent field naming — Using different names in request and response for the same data.
Practice Questions
- What fields does a request body object have?
- How do you support multiple content types?
- How do you make request bodies reusable?
- What is the purpose of the required field?
- How do you provide multiple examples?
Challenge
Design request bodies for an order management API including create order (items, shipping, payment), update order status, add order note, upload order attachment, and bulk order cancellation.
What's Next
In the next lesson, you will learn how to define responses with status codes and schemas.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro