OpenAPI
Overview
OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.
When to use: Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.
When NOT to use: GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.
Quick Reference
| Pattern | Element | Key Points | |||||
|---|---|---|---|---|---|---|---|
| Document root | openapi, info, paths | openapi: '3.1.0' required at top level | |||||
| Path item | /resources/{id} | Curly braces for path parameters | |||||
| Operation | get, post, put, delete, patch | Each operation needs operationId and responses | |||||
| Parameters | `in: path\ | query\ | header\ | cookie` | Path params are always required: true | ||
| Request body | requestBody.content | Keyed by media type (application/json) | |||||
| Response | responses.200.content | At least one response required per operation | |||||
| Component ref | $ref: '#/components/schemas/Name' | Reuse schemas, parameters, responses | |||||
| Schema types | `type: string\ | number\ | integer\ | boolean\ | array\ | object` | Arrays support type: ["string", "null"] in 3.1 |
| Composition | oneOf, anyOf, allOf | Model polymorphism and intersection types | |||||
| Discriminator | discriminator.propertyName | Hint for code generators with oneOf/anyOf | |||||
| Security | securitySchemes + top-level security | Bearer, API key, OAuth2, OpenID Connect | |||||
| Tags | tags on operations | Group operations for documentation | |||||
| Type generation | openapi-typescript | Zero-runtime TypeScript types from spec | |||||
| Typed fetch | openapi-fetch | Type-safe HTTP client using generated types | |||||
| React Query | openapi-react-query | Type-safe React Query hooks from spec | |||||
| Schema-first | zod-openapi | Generate OpenAPI documents from Zod schemas |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Using nullable: true in 3.1 | Use type: ["string", "null"] (3.0 syntax removed) |
Missing operationId on operations | Always set unique operationId for code generation |
Path parameter not in required | Path parameters are always required (required: true) |
| Inline schemas everywhere | Extract to components/schemas and use $ref |
allOf with conflicting required fields | Merge required arrays; allOf unions them |
| Discriminator without shared property | All schemas in oneOf/anyOf must include the discriminator property |
Empty description on responses | Every response needs a meaningful description |
Using type: object without properties | Always define properties or use additionalProperties |
Circular $ref chains | Break cycles with lazy resolution or restructure schemas |
| Mixing 3.0 and 3.1 syntax | Choose one version; 3.1 drops nullable, changes exclusiveMinimum to number |
Delegation
- API design review: Use
Taskagent to audit spec completeness and consistency - Type generation: Use
Exploreagent to find project-specific OpenAPI tooling config - Code review: Delegate to
code-revieweragent for generated client usage patterns
If the typescript-patterns skill is available, delegate advanced TypeScript typing questions to it.