openapi

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 仕様、スキーマ設計、およびコード生成。 REST API の設計、TypeScript クライアントの生成、または API ドキュメントの作成時に使用します。 openapi、swagger、api-spec、スキーマ、コード生成、api-docs、openapi-typescript、zod-openapi に使用します。 ソース: oakoss/agent-skills。