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-patternsskill is available, delegate advanced TypeScript typing questions to it.