openapi

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