How to Write API Documentation in Markdown
Good API documentation is the difference between developers adopting your API in an afternoon and abandoning it in frustration. Markdown is ideal — readable as plain text, renders beautifully, and version-controls cleanly alongside your code.
Core Structure
Every API reference doc needs:
- Overview — what the API does, base URL, authentication
- Authentication — how to obtain and use credentials
- Endpoints — one section per endpoint
- Error Reference — every error code with its meaning
- Rate Limits — throttling rules and headers
Documenting an Endpoint
markdown## GET /users/{id}
Retrieve a single user by their ID.
**Authentication:** Bearer token required
### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | The user's unique identifier |
### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| include | string | — | Relations to include (e.g. `posts,followers`) |
### Request Example
```bash
curl -X GET https://api.example.com/users/usr_123 \
-H "Authorization: Bearer YOUR_TOKEN"
Response (200 OK)
json{
"id": "usr_123",
"name": "Jane Doe",
"email": "[email protected]",
"created_at": "2024-01-15T10:30:00Z"
}
Error Responses
| Code | Description |
|---|---|
| 401 | Missing or invalid authentication token |
| 404 | User not found |
## Documenting Authentication
```markdown
## Authentication
Include your API key in every request:
```bash
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Security: Never expose API keys in client-side code or commit them to version control. Use environment variables.
## Error Reference Section
```markdown
## Error Reference
All errors follow this format:
```json
{
"error": {
"code": "user_not_found",
"message": "No user with ID usr_123 exists"
}
}
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Request body failed validation |
| 401 | unauthorized | Missing or invalid API key |
| 404 | not_found | Resource doesn't exist |
| 429 | rate_limited | Too many requests |
| 500 | server_error | Internal error |
## Rate Limits
```markdown
## Rate Limits
| Plan | Requests/minute | Requests/day |
|------|----------------|--------------|
| Free | 60 | 1,000 |
| Pro | 600 | 50,000 |
Rate limit headers in every response:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 42 X-RateLimit-Reset: 1705312800
Best Practices
Use Real Examples
Always use realistic values — not string, 123, or foo. Readers copy-paste examples.
Document Every Field
Even optional ones. Undocumented fields become support tickets.
Note Deprecations
markdown> **Deprecated:** The `username` field is deprecated as of v2.1. Use `handle` instead. Will be removed in v3.0 (2026-Q3).
Link from Errors to Docs
Add a docs URL in error responses pointing to the relevant docs page.
Complementary Tools
- OpenAPI/Swagger — machine-readable spec; generate markdown with
widdershins - Redoc / Stoplight — render OpenAPI specs beautifully
- Docusaurus — static site with excellent code block support
Draft your API docs in MarkGenie's editor to preview tables and code blocks before committing.