How do I document REST endpoints with request and response examples?

A good REST API doc usually includes, for each endpoint:

1. What it does
2. Method and path
3. Auth requirements
4. Request parameters
5. Request body example
6. Response examples for success and error cases
7. Status codes

Recommended structure

1) Endpoint overview

### Create a user
Creates a new user account.

2) Method and URL

POST /api/users

3) Headers

Authorization: Bearer <token>
Content-Type: application/json

4) Request body

List fields with type, required/optional, and description.

Field	Type	Required	Description
name	string	yes	User’s full name
email	string	yes	User’s email address
age	integer	no	User’s age

### 5) Request example
```json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "age": 29
}

6) Response examples

Success: 201 Created

{
  "id": "usr_123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "age": 29,
  "createdAt": "2026-10-04T12:34:56Z"
}

Error: 400 Bad Request

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Must be a valid email address"
    }
  ]
}

7) Status codes

- 201 Created — User created successfully
- 400 Bad Request — Invalid input
- 401 Unauthorized — Missing/invalid token
- 409 Conflict — Email already exists

---

Best practices

• Show one real example per common case: success, validation error, auth error.
• Keep examples consistent with the actual schema and naming.
• Document formats: dates, enums, IDs, nullability.
• Use code blocks with syntax highlighting (json, bash, etc.).
• Include curl examples for quick testing:

curl -X POST "https://api.example.com/api/users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "age": 29
  }'

---

If you want a standard format

If you’re using OpenAPI/Swagger, you can document request/response examples directly in YAML/JSON and generate interactive docs from it.

Example:

paths:
  /api/users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Jane Doe
              email: jane@example.com
              age: 29
      responses:
        "201":
          description: Created
          content:
            application/json:
              example:
                id: usr_123
                name: Jane Doe
                email: jane@example.com
                age: 29

If you want, I can give you:

• a Markdown template
• an OpenAPI example
• or a fully documented endpoint example for your API.