---
description: "OpenAPI/Swagger API documentation standards — applied when editing API spec files"
globs: ["**/openapi*", "**/swagger*"]
---
# OpenAPI

- Use OpenAPI 3.0+ specification
- Define reusable schemas in `components/schemas`; reference with `$ref`
- Include `description` for every endpoint, parameter, and schema property
- Define `responses` for at least 200, 400, 401, 404, 500
- Use `tags` to group endpoints by domain
- Include `examples` for request/response bodies
- Version the API in the path (`/api/v1/`) or via header
- Use `operationId` for code generation compatibility