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