openapi-documentationlisted

# 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 respon