openapi-documentation

OpenAPI Documentation

Write OpenAPI 3.0 specs that are accurate enough to generate a working client from, not just descriptive prose that happens to be near the code.

When to use

• Creating or updating an OpenAPI/Swagger spec for a REST API.
• An endpoint's request/response shape, auth requirement, or error surface changed and the spec needs to catch up.
• Skip for non-HTTP internal APIs/functions, and skip for GraphQL (which has its own schema/introspection story, not OpenAPI's).

Key responsibilities

1. Create OpenAPI 3.0-compliant specifications — validate against the spec, not just "looks right."
2. Document every endpoint with both a summary and a fuller description — the summary is what shows up in a collapsed list view, so it has to stand alone.
3. Define request/response schemas accurately, including every field's type and whether it's required.
4. Include authentication and security schemes — an endpoint's auth requirement is part of its contract, not an implementation detail to omit.
5. Provide a real example for every operation — a schema without an example makes the reader reconstruct a valid payload by hand.

Best practices

• Use descriptive summaries and descriptions — "Get user" tells a reader nothing an endpoint path didn't already say; "Get a user's profile, including their current subscription tier" does.
• Include example requests and responses, not just one or the other.
• Document every realistic error response (400/401/403/404/409/5xx), not just the 200 case — the error surface is as much a contract as success.
• Use $ref for reusable components (schemas, responses, parameters) — duplicated inline schemas drift out of sync with each other.
• Follow the OpenAPI 3.0 specification strictly, not "close enough" — strict compliance is what makes codegen and client tooling actually work.
• Group endpoints logically with tags so the generated docs UI is navigable, not one flat list.

Structure