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.
Specifiche OpenAPI 3.1, progettazione dello schema e generazione del codice. Da utilizzare durante la progettazione di API REST, la generazione di client TypeScript o la creazione di documentazione API. Utilizzare per openapi, spavalderia, api-spec, schema, generazione di codice, api-docs, openapi-typescript, zod-openapi. Fonte: oakoss/agent-skills.