Markdown to API Doc Guide

API documentation usually begins as rough Markdown in a pull request, a product note, or a model-generated draft. That is fine for capture, but rough notes are hard to reuse unless headings, examples, and request sections follow a repeatable shape.

1. Give each endpoint a stable top-level section

Start with the action name or route, then use predictable subheadings like Request body, Query parameters, Headers, and Response. Readers skim docs by structure before they read details.

2. Keep examples close to the section they explain

Putting JSON examples immediately under the request or response heading shortens the path from concept to implementation. It also makes conversion into HTML or an internal portal more reliable because each block already has a clear role.

3. Preview the result before publishing

Converting Markdown to HTML is not just about cosmetics. Previewing catches malformed lists, unclosed code fences, and heading drift that can break your generated table of contents.

4. Suggested endpoint template

If your team documents many endpoints, start from a lightweight template and fill only what is relevant. Consistent structure reduces cognitive load for both maintainers and API consumers.

## POST /v1/orders

### Purpose
Create a new order for a customer.

### Headers
- Authorization: Bearer {token}
- Content-Type: application/json

### Request Body
```json
{ "customerId": "cus_123", "items": [{ "sku": "A-1", "qty": 2 }] }
```

### Response
```json
{ "id": "ord_987", "status": "created" }
```

5. Common documentation quality issues

• Missing error examples: include at least one non-2xx response with a realistic body.
• Unclear field constraints: document ranges, allowed enums, and required/optional semantics explicitly.
• Detached examples: keep code blocks next to the section they explain to avoid ambiguity.
• Drifting headings: inconsistent heading levels break generated navigation and fragment links.

6. Publish checklist

1. Verify all endpoint paths and HTTP methods match production routes.
2. Re-run examples and ensure payloads are still valid JSON.
3. Check links and anchor headings after Markdown conversion.
4. Keep one owner per doc section so updates are not orphaned.