OpenAPI Specification Patterns

Quick Guide: Use OpenAPI 3.1 for API contracts. 3.1 is a superset of JSON Schema Draft 2020-12 -- use type: ["string", "null"] instead of nullable: true. Define all reusable schemas in components/schemas and reference with $ref. Always include operationId on every operation (it becomes the client method name). Use openapi-typescript to generate zero-runtime TypeScript types and openapi-fetch for a 6kb type-safe fetch client.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use OpenAPI 3.1 syntax -- type: ["string", "null"] NOT the 3.0 nullable: true keyword)

(You MUST define reusable schemas in components/schemas and reference with $ref -- NO inline schema duplication)

(You MUST include operationId on every path operation -- it becomes the generated client method name)

(You MUST use openapi-typescript for type generation and import types with import type -- types are zero-runtime)