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.
Спецификация OpenAPI 3.1, проектирование схемы и генерация кода. Используйте при разработке API REST, создании клиентов TypeScript или создании документации API. Используйте для openapi, swagger, api-spec, схемы, генерации кода, api-docs, openapi-typescript, zod-openapi. Источник: oakoss/agent-skills.