Write Api Docs

---
name: write-api-docs
description: Use when writing or improving API reference documentation, endpoint descriptions, or OpenAPI specifications
source: "Docs for Developers (Bhatti et al., 2021); Stripe API Docs; OpenAPI Initiative Specification 3.1"
tags: [api, documentation, openapi, reference, technical-writing]
verified: true
---

# Write API Docs

Write clear, complete API reference documentation that developers trust and can use without guessing.

## Why This Is Best Practice

**Adopted by:** Stripe, Twilio, GitHub, and Shopify — consistently ranked top developer-experience APIs

**Impact:** Stripe attributes low support volume directly to documentation quality; Twilio reports 30%+ faster onboarding for customers who read docs before integrating

**Why best:** Well-written API docs reduce integration time and support burden simultaneously. Developers treat docs as a contract — ambiguity breaks trust permanently. The OpenAPI Specification enforces machine-readable consistency while Stripe's style demonstrates the narrative layer on top.

## Steps

1. **Define the audience and use cases** — identify whether readers are integrating for the first time or looking up edge cases; write for both with layered depth
2. **Structure each endpoint entry** — include: purpose sentence, HTTP method + path, authentication requirement, all parameters with types/constraints/defaults, request example, response schema, error codes
3. **Write the purpose sentence first** — one plain-language sentence explaining what the endpoint does and when to use it, before any technical detail
4. **Provide runnable examples** — show real request/response pairs with realistic values, not `string` placeholders; include `curl` and at least one SDK snippet
5. **Document every error code** — list status codes the endpoint can return, the condition that triggers each, and the recommended recovery action
6. **Write an OpenAPI spec in parallel** — keep narrative docs and machine-readable spec in sync; spec drives SDK generation and lint tooling
7. **Add changelog entries** — note deprecations, new fields, and breaking changes at the top of each affected page with version and date

## Rules

- Every parameter must state: type, whether required or optional, default value, and valid range or enum values
- Never use `foo`, `bar`, or `string` as example values — use realistic domain data
- Breaking changes must be called out with a deprecation notice and migration path
- Code examples must be copy-paste executable without modification
- Authentication must be documented on every endpoint, not just a getting-started page

## Examples

**Bad:** `POST /charges` — Creates a charge.

**Good:** `POST /charges` — Creates a new charge against a customer's payment method. Use this endpoint to collect a one-time payment; for recurring billing, use the Subscriptions API instead.

## Common Mistakes

- Documenting only the happy path: developers need error states more than success states when debugging at 2 AM
- Letting examples drift from the schema: contradictions destroy trust faster than missing docs
- Burying authentication requirements: state them at the top of every endpoint, not just in an intro section

## When NOT to Use

- Do not apply this skill to internal-only APIs consumed by a single team that owns both producer and consumer, where informal inline code comments and a team wiki page provide sufficient shared context without the overhead of formal reference documentation.
- Do not use this skill for GraphQL APIs where the schema is self-describing and tools like GraphiQL or Apollo Sandbox auto-generate interactive reference; applying this skill's narrative-layer approach to a self-documenting schema creates duplicate, drift-prone content.
- Do not apply this skill before the API contract is stable; writing full reference docs against an actively changing interface produces documentation debt faster than it produces value, and the effort is better spent on a draft OpenAPI spec reviewed by consumers first.