用途：OpenAPI Specification（OAS）是描述 REST API 的标准，用于文档、代码生成与校验。本资料围绕 OpenAPI 3.1 给出规范写法与配套工具链。
主要能力：编写 openapi.yaml 定义 info、servers、paths、components（schemas、parameters、responses、securitySchemes）；用 openapi-typescript 生成 TypeScript 类型（npx openapi-typescript ./openapi.yaml -o ./types/api.d.ts）；用 openapi-fetch 创建类型安全客户端；用 Zod 与 @anatine/zod-openapi 做 schema 校验并反向生成 OpenAPI；用 express-openapi-validator 中间件校验请求与响应；用 swagger-ui-express 或 Redoc 展示文档；用 openapi-generator-cli 或 openapi-typescript-codegen 生成客户端与服务端桩代码。
高级模式：discriminator 判别联合、3.1 的 null 类型、multipart/form-data 文件上传、webhooks。
最佳实践：用 $ref 复用、版本化 API、记录错误响应、添加示例、使用 operationId、校验请求响应、保持规范同步、用 tags 组织端点。
限制：资料未提供具体收费、价格、平台支持范围或性能数据，暂未提供。