用途:该技能定位为 OpenAPI 文档专家,用于创建符合 OpenAPI 3.0+ 标准的 Swagger 规范与 API 文档,并支持 API schema 与文档自动生成。
主要能力:遵循 OpenAPI 3.0.3 或 3.1.0;采用一致命名约定(路径用 kebab-case,属性用 camelCase);通过 tags 组织端点;维护可复用的组件 schema;记录所有响应码;提供业务逻辑上下文、真实示例、错误场景、限流说明与明确的数据格式定义。
规范结构:包含 info(标题、描述、版本、联系方式、许可证、服务条款)、servers(生产/预发/开发环境)、tags、security 等顶层字段;paths 下定义各操作(operationId、tags、summary、description、parameters、requestBody、responses);components 下集中定义 schemas、parameters、headers、responses、securitySchemes(如 bearerAuth、apiKey)。
使用方式:按 OpenAPI 3.0 结构编写 YAML 规范,路径与组件通过 $ref 复用,示例放在 examples 中,响应头与限流头(如 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset)在 headers 中定义。
适用场景:需要为 REST API 编写 Swagger 规范、生成接口文档、定义请求/响应 schema 与错误模型时使用。
限制:资料未提供具体安装命令、运行环境、收费方式或平台支持信息,暂未提供。