API Documentation
Write effective API documentation: OpenAPI 3.1 spec, auto-generated docs, code examples in multiple languages, change management, and developer portal best practices.
Good API documentation is the single biggest factor in developer adoption. It requires accurate specifications (OpenAPI), working code examples, a clear changelog, and a developer portal that makes onboarding fast. Auto-generating docs from code keeps them up to date.
Documentation is a product feature, not an afterthought. Use OpenAPI 3.1 as the source of truth - generate docs from spec, not the reverse. Every endpoint needs a working example. Document errors as thoroughly as success cases.
Workflow
- Write the OpenAPI 3.1 specificationOpenAPI is the industry standard for REST API description - tools generate docs, SDKs, and mocks from it.
- Auto-generate from codeHand-maintained docs drift from implementation - generating from code keeps them accurate.
- Write working code examplesDevelopers copy-paste examples - non-working examples erode trust and waste developer time.
- Document errors and edge casesDevelopers spend more time debugging errors than success paths - documenting errors is high-leverage.
- Maintain a changelog and versioningDevelopers need to know what changed and how to migrate - a clear changelog reduces support burden.
Output Format
OpenAPI 3.1 spec validated by Redocly, auto-generated from code annotations, Scalar or Redoc for UI, working curl + JS examples, error code reference, semantic versioned changelog.
Examples
OpenAPI example: `paths: /orders: post: requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateOrderRequest" examples: standard: summary: Standard order value: { items: [{ productId: "prod_123", quantity: 2 }], shippingAddress: { street: "123 Main St", city: "Portland", zip: "97201" } }`Scalar integration: `import { apiReference } from "@scalar/express-api-reference"; app.use("/docs", apiReference({ spec: { url: "/openapi.json" }, theme: "purple", authentication: { preferredSecurityScheme: "bearerAuth" } }))`Changelog: `## [1.5.0] - 2026-03-01 ### Added - `POST /webhooks` endpoint for configuring webhook destinations - `X-RateLimit-Reset` header on all responses ### Deprecated - `GET /v1/events` will be removed 2026-09-01; use `GET /v2/events` with cursor pagination`Edge Cases & Gotchas
- API key in examples: never include real API keys in docs. Use clearly fake values: `sk_test_xxxxxxxxxxxxx`. Document where to generate keys in the getting-started guide
- Versioning strategy: URL path versioning (`/v1/`) is more discoverable than header versioning. When introducing v2, maintain both for the deprecation window
- Localization: for global APIs, document whether string fields (error messages, display text) are localized or always English
When to Break These Rules
- For internal-only APIs consumed by your own team, lightweight documentation (README, TypeScript types, Postman collection) is sufficient - a full developer portal is overkill.
Reference Files
OpenAPI specification: https://spec.openapis.org/oas/v3.1.0Scalar: https://scalar.com/Redocly CLI: https://redocly.com/docs/cli/Developer portal best practices: https://stripe.com/docs (Stripe docs as the gold standard)