Document a REST API in Markdown

API documentation in Markdown lives alongside the code in the same repository, making it easy to update docs as part of the same pull request that changes the API. This "docs as code" approach keeps documentation from drifting out of sync with the implementation and gives developers the same review workflow for documentation changes as for code changes. GitHub, GitLab, and most documentation platforms render Markdown to HTML automatically. This template documents a single REST endpoint in the format that developers find most immediately useful: the HTTP method and path at the top so you can identify what this page documents at a glance, a brief description of what the endpoint does, the authentication requirement, a parameter table listing each field with its type and whether it's required, a ready-to-run curl example that developers can copy directly to their terminal, the expected success response with a realistic example body, and an error table mapping status codes to their meanings. The parameter table format uses GitHub-flavored Markdown table syntax: columns are separated by pipes, and a row of dashes separates the header from the data rows. GitHub renders this as a properly formatted HTML table. The three essential columns are parameter name, type (string, integer, boolean, uuid, etc.), required flag, and description. Adding a Format or Example column is valuable for fields with specific formats like dates, UUIDs, or phone numbers. The curl example is one of the most valuable parts of endpoint documentation: developers copy it, replace TOKEN and the endpoint URL with their actual values, and test the API in seconds without writing any code. Always include -H "Authorization: Bearer TOKEN" for authenticated endpoints and show the actual request body for POST/PUT endpoints. Show the real endpoint URL structure, not a placeholder that requires additional documentation to decode. Response schema documentation is often the most time-consuming part to maintain. Two approaches: document it manually in a table (as shown here, or in a separate Parameters section) or reference your OpenAPI spec where the schema is defined programmatically. For teams with an OpenAPI spec, generating documentation from the spec using tools like Redoc or Stoplight is more maintainable than maintaining parallel Markdown documentation. Real-world documentation structures: a docs/ directory at the repository root with one Markdown file per API endpoint, an index file listing all endpoints, and a getting-started guide covering authentication and common workflows. This structure works well for APIs with up to 50 endpoints; larger APIs benefit from a dedicated documentation platform. Tips: include error examples alongside success examples, especially for common error scenarios like 401 Unauthorized and 422 Validation Error. Developers spend more time debugging errors than happy paths, and good error documentation reduces support burden significantly.

## GET /users/:id

Returns a single user by ID.

**Authentication:** Bearer token required

### Path Parameters

| Parameter | Type   | Required | Description  |
|-----------|--------|----------|--------------|
| id        | string | Yes      | User UUID    |

### Request Example

```bash
curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/users/usr_123
```

### Response 200

```json
{
  "id": "usr_123",
  "name": "Jane Smith",
  "email": "[email protected]",
  "createdAt": "2026-01-15T10:30:00Z"
}
```

### Errors

| Code | Meaning       |
|------|---------------|
| 401  | Unauthorized  |
| 404  | User not found|