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 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. Source: oakoss/agent-skills.