# name: writing-api-documentation description: Writes API endpoint and SDK reference documentation with complete per-endpoint entries, copy-paste runnable examples, and errors documented as thoroughly as successes. Use when the user asks to document an API, write endpoint reference docs, an API reference page, SDK docs, or improve OpenAPI/Swagger descriptions. Do not use for conceptual guides and READMEs, tutorials, or designing the API itself — separate skills cover those.

# Writing API Documentation

# When to use / when NOT to use

• Use for: endpoint reference pages, SDK method reference, OpenAPI descriptions, error catalogs, API changelogs.
• Do NOT use for: conceptual guides and READMEs (writing-technical-documentation), step-by-step tutorials (writing-tutorials), or designing the API's shape (backend-skills/designing-rest-apis).

# House rules

1. Auth section first. It's the #1 lookup; put "Authentication" before any endpoint.

   • ✅ "All requests require Authorization: Bearer sk_live_…. Get a key at Settings → API."
   • ❌ Auth explained under a FAQ at the bottom.

2. Every endpoint gets the full block, no exceptions: method + path, one-line purpose, auth requirement, parameter table, request example, response example, error table.

   • ✅ POST /v1/invoices documented with all seven parts.
   • ❌ "Works like the orders endpoint but for invoices."

3. Examples are copy-paste runnable. curl by default, complete headers, real-looking fake data.

   • ✅ curl https://api.acme.com/v1/invoices -H "Authorization: Bearer sk_test_51H..." -d amount=1999 -d currency=usd
   • ❌ curl <endpoint> -d foo=bar

4. Parameter tables with five columns: name / type / required / default / constraints.

   • ✅ | amount | integer | yes | — | cents, 50–999999 |
   • ❌ "Takes an amount and an optional currency."

5. Document errors as thoroughly as successes. Every error code: when it happens and how the caller fixes it.

   • ✅ | 402 | card_declined | Card was declined | Ask the customer for another card |
   • ❌ "Returns standard HTTP error codes."

6. Show the response, not a description of it. Full JSON body with realistic values, fields explained inline or in a table.

   • ✅ A complete 200 JSON example plus a field table.
   • ❌ "Returns the created invoice object."

7. Breaking changes go in a changelog with dates and migration notes.

   • ✅ "2026-06-01 — total renamed to amount_total. Both returned until 2026-09-01."
   • ❌ Silent renames discovered in production.

8. OpenAPI is the source of truth for shapes; prose carries concepts (pagination, idempotency, rate limits) once, linked everywhere.

# Workflow

1. Inventory: list every endpoint/method to document; flag undocumented errors by reading the handler code if available.
2. Write the shared sections once: Authentication (first), pagination, idempotency, rate limits, error format.
3. For each endpoint, fill the full block from rule 2 — write the error table before polishing the happy path.
4. Run every example against a test environment (or validate against the OpenAPI spec if no environment exists) and paste real output as the response example.
5. Self-review: scan for "foo/bar" data, missing defaults in parameter tables, and error tables with fewer than two entries; fix before delivering.

# Edge cases

• No test environment to run examples → validate request/response examples against the OpenAPI schema and mark them "generated from spec".
• Endpoint with side effects (payments, deletion) → example uses test-mode keys/sandbox data and says so.
• Huge API → document by resource, one page per resource, identical block structure; never summarize "similar" endpoints together.

# References

Extended before/after examples: see references/examples.md.