用途：根据代码或设计产出并维护 OpenAPI（Swagger）规范，使 API 有文档可依，并支持工具生成客户端、模拟服务或做校验。
主要能力：定义或更新路径与操作（path、HTTP 方法、summary、operationId、tags）；定义请求与响应（参数、请求体 schema、至少 200/201 与 4xx/5xx 响应）；用 components/schemas 与 $ref 复用；通过 securitySchemes 记录认证并全局或按操作应用；为重要请求/响应添加示例；校验规范并放置到仓库、从 README 或文档链接。
使用方式：先确定事实来源——从设计（按约定 API 设计起草路径与 schema）或从代码（由路由定义与类型推导）；若项目已有规范则就地更新并保持风格一致。按路径与操作逐项编写，错误响应可复用 components/responses。规范结构包含顶层 openapi、info、servers、paths、components、security。校验可用 Swagger Editor、npx @apidevtools/swagger-cli validate openapi.yaml 或 openapi-generator，修复报错后再提交。生成客户端可用 openapi-generator、swagger-codegen 或语言专用工具（如 openapi-typescript），查看可用 Swagger UI 或 Redoc。
适用场景：为消费者或代码生成记录 REST API；新增端点或变更请求/响应结构；从规范生成客户端 SDK 或模拟服务器。
限制与规则：不得编造端点或字段，须匹配实际 API 或已达成一致的设计，含糊处写入 description 并标注待核实；已有规范就地更新，保持结构与命名一致；认证写入 securitySchemes 并应用到受保护路径，公开路径可用空 security 标记；schema 与响应放入 components 并用 $ref 引用以避免重复；规范与 API 变更应在同一 PR 更新，可考虑 CI 检查。命名约定：schema 用 PascalCase，operationId 用 camelCase，路径小写、多词用 kebab-case。避免在每个响应内联巨大 schema、只记录 200 响应、规范中缺少认证等反模式。具体收费、价格、平台与效果资料暂未提供。