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، أو إنشاء عملاء TypeScript، أو إنشاء وثائق واجهة برمجة التطبيقات. يستخدم لـ openapi، وswagger، وapi-spec، والمخطط، وتوليد التعليمات البرمجية، وapi-docs، وopenapi-typescript، وzod-openapi. المصدر: oakoss/agent-skills.