OpenAPI
Document API endpoints using OpenAPI integration and MDX
Create API documentation pages by adding the openapi field to your MDX frontmatter. Docs Kit automatically generates comprehensive documentation from your OpenAPI specification.
---
title: "Get User"
description: "Retrieve a user by their unique identifier"
openapi: "GET /api/users/{id}"
published: true
---
## Additional Context
You can add custom content above or below the auto-generated API documentation.
Use this space to provide:
- Usage examples
- Best practices
- Common pitfalls
- Related endpointsOpenAPI endpoint reference in the format: METHOD /path
Format: "METHOD /endpoint/path"
Examples:
"GET /api/users""POST /api/users""PUT /api/users/{id}""DELETE /api/users/{id}"Must match an endpoint in your OpenAPI specification exactly.
When you add openapi frontmatter, Docs Kit automatically displays:
Shows method badge (GET, POST, etc.) and full endpoint path with syntax highlighting for path parameters.
All parameters grouped by location:
{id}For POST/PUT/PATCH requests:
Response documentation for each status code:
Auto-generated code snippets in multiple languages:
Interactive button to test the endpoint directly from documentation.
---
title: "List Users"
description: "Retrieve a paginated list of users"
openapi: "GET /api/users"
published: true
---
## Overview
This endpoint returns all users with support for pagination and filtering.
## Query Parameters
The endpoint supports the following filters:
- Role-based filtering
- Date range filtering
- Text search across name and email---
title: "Create User"
description: "Create a new user account"
openapi: "POST /api/users"
published: true
---
## Creating Users
When creating a user, ensure the email is unique and the password meets security requirements:
- Minimum 8 characters
- At least one uppercase letter
- At least one number
- At least one special character
## Email Verification
New users receive a verification email. The account remains inactive until verified.---
title: "Update User"
description: "Update an existing user's information"
openapi: "PUT /api/users/{id}"
published: true
---
## Partial Updates
This endpoint supports partial updates. Only include fields you want to change.
Unchanged fields retain their current values.
## Validation
All updates are validated before being saved:
- Email must be unique
- Username must be 3-20 characters
- Role must be valid enum value---
title: "Delete User"
description: "Permanently delete a user account"
openapi: "DELETE /api/users/{id}"
published: true
---
## Soft vs Hard Delete
<Callout status="warning" title="Permanent Action">
This performs a hard delete. The user and all associated data are permanently
removed.
</Callout>
For soft deletes, use the `PATCH /api/users/{id}` endpoint with `status: "deleted"`.
## Cascade Behavior
Deleting a user also deletes:
- User sessions
- API tokens
- Uploaded files
- Activity historyMix generated API docs with custom content:
---
title: "Send Email"
description: "Send a transactional email"
openapi: "POST /api/emails/send"
published: true
---
## Before You Start
<Steps>
<Step title="Get API Key">
Generate an API key from the dashboard
</Step>
<Step title="Verify Domain">
Add your sending domain and verify DNS records
</Step>
<Step title="Test in Sandbox">
Use sandbox mode for testing before going live
</Step>
</Steps>
## After Sending
The API returns immediately with a message ID. Email delivery is asynchronous.
Track delivery status using:
- Webhooks (recommended)
- Status API endpoint
- Dashboard logs
## Best Practices
<Tabs>
<Tab title="Templates">
Use email templates for consistent branding and easier maintenance.
</Tab>
<Tab title="Personalization">
Include merge variables for personalized content: `{{user.name}}`
</Tab>
<Tab title="Testing">
Always test emails before sending to real users:
```json
{
"to": "test@example.com",
"sandbox": true
}
```
</Tab>
</Tabs>
## File Organization
Organize API pages by resource or feature:
```text
content/api-reference/
users/
list.mdx (GET /users)
create.mdx (POST /users)
get.mdx (GET /users/{id})
update.mdx (PUT /users/{id})
delete.mdx (DELETE /users/{id})
authentication/
login.mdx (POST /auth/login)
logout.mdx (POST /auth/logout)
refresh.mdx (POST /auth/refresh)
webhooks/
create.mdx (POST /webhooks)
list.mdx (GET /webhooks)
delete.mdx (DELETE /webhooks/{id})
```Add API pages to docs.config.ts:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users",
"pages": [
"/api-reference/users/list",
"/api-reference/users/create",
"/api-reference/users/get",
"/api-reference/users/update",
"/api-reference/users/delete"
]
},
{
"group": "Authentication",
"pages": [
"/api-reference/authentication/login",
"/api-reference/authentication/logout"
]
}
]
}
]
}
}If you see "Endpoint not found in OpenAPI spec":
openapi value exactly matches your specIf auto-generated sections are missing:
requestBody is defined for POST/PUT/PATCHresponses object is populatedexample or examples fields to your specNext, explore Interactive Features like the "Try It" button.