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
Task agent to audit spec completeness and consistency
- Type generation: Use
Explore agent to find project-specific OpenAPI tooling config
- Code review: Delegate to
code-reviewer agent for generated client usage patterns
If the typescript-patterns skill is available, delegate advanced TypeScript typing questions to it.
References
- Schema design: paths, operations, parameters, components, and $ref
- Data types: formats, composition, discriminators, and nullable
- Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI
- Documentation: Swagger UI, Redoc, and API docs best practices
1---2name: openapi3description: OpenAPI 3.1 specification, schema design, and code generation. Use when designing REST APIs, generating TypeScript clients, or creating API documentation. Use for openapi, swagger, api-spec, schema, code-generation, api-docs, openapi-typescript, zod-openapi.4license: MIT5---6
7# OpenAPI
8
9## Overview
10
11OpenAPI 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.
12
13**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.
14
15**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.
16
17## Quick Reference
18
19| Pattern | Element | Key Points |
20| --------------- | ------------------------------------------------------- | -------------------------------------------------- |
21| Document root | `openapi`, `info`, `paths` | `openapi: '3.1.0'` required at top level |
22| Path item | `/resources/{id}` | Curly braces for path parameters |
23| Operation | `get`, `post`, `put`, `delete`, `patch` | Each operation needs `operationId` and `responses` |
24| Parameters | `in: path\|query\|header\|cookie` | Path params are always `required: true` |
25| Request body | `requestBody.content` | Keyed by media type (`application/json`) |
26| Response | `responses.200.content` | At least one response required per operation |
27| Component ref | `$ref: '#/components/schemas/Name'` | Reuse schemas, parameters, responses |
28| Schema types | `type: string\|number\|integer\|boolean\|array\|object` | Arrays support `type: ["string", "null"]` in 3.1 |
29| Composition | `oneOf`, `anyOf`, `allOf` | Model polymorphism and intersection types |
30| Discriminator | `discriminator.propertyName` | Hint for code generators with `oneOf`/`anyOf` |
31| Security | `securitySchemes` + top-level `security` | Bearer, API key, OAuth2, OpenID Connect |
32| Tags | `tags` on operations | Group operations for documentation |
33| Type generation | `openapi-typescript` | Zero-runtime TypeScript types from spec |
34| Typed fetch | `openapi-fetch` | Type-safe HTTP client using generated types |
35| React Query | `openapi-react-query` | Type-safe React Query hooks from spec |
36| Schema-first | `zod-openapi` | Generate OpenAPI documents from Zod schemas |
37
38## Common Mistakes
39
40| Mistake | Correct Pattern |
41| ------------------------------------------ | ------------------------------------------------------------------------------ |
42| Using `nullable: true` in 3.1 | Use `type: ["string", "null"]` (3.0 syntax removed) |
43| Missing `operationId` on operations | Always set unique `operationId` for code generation |
44| Path parameter not in `required` | Path parameters are always required (`required: true`) |
45| Inline schemas everywhere | Extract to `components/schemas` and use `$ref` |
46| `allOf` with conflicting `required` fields | Merge `required` arrays; `allOf` unions them |
47| Discriminator without shared property | All schemas in `oneOf`/`anyOf` must include the discriminator property |
48| Empty `description` on responses | Every response needs a meaningful `description` |
49| Using `type: object` without `properties` | Always define `properties` or use `additionalProperties` |
50| Circular `$ref` chains | Break cycles with lazy resolution or restructure schemas |
51| Mixing 3.0 and 3.1 syntax | Choose one version; 3.1 drops `nullable`, changes `exclusiveMinimum` to number |
52
53## Delegation
54
55- **API design review**: Use `Task` agent to audit spec completeness and consistency
56- **Type generation**: Use `Explore` agent to find project-specific OpenAPI tooling config
57- **Code review**: Delegate to `code-reviewer` agent for generated client usage patterns
58
59> If the `typescript-patterns` skill is available, delegate advanced TypeScript typing questions to it.
60
61## References
62
63- [Schema design: paths, operations, parameters, components, and $ref](references/schema-design.md)
64- [Data types: formats, composition, discriminators, and nullable](references/data-types.md)
65- [Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI](references/code-generation.md)
66- [Documentation: Swagger UI, Redoc, and API docs best practices](references/documentation.md)
oakoss