用途
openapi-review 用于系统化审查 OpenAPI（Swagger）规范文件，检查其是否符合 OpenAPI 3.1 标准，并评估安全方案设计、API 设计最佳实践以及文档质量。
输入处理
该技能会先判断输入类型并据此获取规范内容：
- 直接内容：规范以内联方式出现在对话中，直接审查。
- 文件路径：读取指定的 .yaml、.yml 或 .json 文件。
- 目录路径：递归查找所有 OpenAPI 规范文件；若找到多个，会询问用户要审查哪一个。
- URL：若提供 URL，会要求用户直接提供文件内容。
开始审查前，会确定规范的格式（YAML 或 JSON）、版本（OpenAPI 2.0 Swagger、3.0.x 或 3.1.x）以及结构（单文档或通过 $ref 引用外部文件的多文件）。若规范使用 OpenAPI 2.0 或 3.0.x，会指出版本差异，并在有益时建议迁移到 3.1.x。
审查流程
开始审查前需阅读 references/openapi-checklist.md。审查按以下阶段依次执行，每个发现的问题都会被赋予严重级别。
阶段一：结构合规
验证规范是否符合 OpenAPI 3.1 结构：必需字段（openapi 版本字符串、info.title、info.version，以及 paths、components、webhooks 中至少一个）；$ref 解析（所有 $ref 指针解析到有效目标，无循环引用）；路径模板（路径参数匹配 {paramName} 语法并有对应参数定义，模板解析后无重复路径）；参数唯一性（每个操作内参数按 name 与 in 的组合唯一）；operationId 唯一性（整个规范中每个 operationId 唯一）；参数 schema（简单值用 schema，复杂序列化用 content，不可同时使用）；媒体类型（请求/响应 content 键为有效媒体类型）；状态码（响应状态码为有效 HTTP 码或 default，范围码 2XX、4XX 使用正确）。
阶段二：安全审查
检查安全定义及其应用：方案定义（components/securitySchemes 中至少存在一个安全方案）；全局或按操作安全（安全全局应用或应用于每个操作，标记缺少安全且未用空数组 [] 显式退出的操作）；OAuth2 流程（OAuth2 方案具有有效的流程配置、正确的授权与令牌 URL，作用域定义并一致使用）；API 密钥位置（API 密钥使用 header 或 cookie，而非 query）；HTTPS 强制（所有 servers[].url 使用 https://，标记非 localhost 或 127.0.0.1 的 http:// URL）；敏感数据暴露（密码、令牌、密钥等敏感标识符不在路径或查询参数中，应使用 header 或请求体）；CORS 考虑（若 API 被浏览器消费，指出响应定义中是否缺少安全相关 header）。
阶段三：API 设计最佳实践
评估 API 设计是否符合 RESTful 约定与一致性：资源命名（路径使用复数名词，如 /users 而非 /user；路径中无动词；多词段使用小写加连字符）；命名一致性（属性名全程遵循单一约定，不混用 camelCase 与 snake_case）；HTTP 方法使用（GET 用于检索且无请求体，POST 用于创建，PUT 用于完整替换，PATCH 用于部分更新，DELETE 用于删除，标记误用）；分页（返回数组的 GET 列表端点包含分页参数与响应元数据）；状态码（按方法使用恰当状态码，如 POST 创建用 201、DELETE 无体用 204、资源端点记录 404、冲突场景用 409）；版本管理（一致的版本策略，标记混用方式）；组件复用（共享 schema、参数、响应定义在 components 中并通过 $ref 引用，标记内联重复）；operationId 约定（描述性且遵循一致模式）；描述（所有操作、参数、schema 具有有意义的 description 字段）。
阶段四：Schema 与文档质量
评估 schema 完整性与文档：schema 完整性（定义 type，适当使用 format，为必填属性设置 required 数组，为固定值集定义 enum，提供 example 或 examples）；discriminator 使用（多态 schema 使用 discriminator 并指定有效 propertyName 与可选 mapping）；请求/响应示例（操作在媒体类型对象中包含 example 或 examples，示例真实且与 schema 约束一致）；错误响应（定义 4xx 与 5xx 响应并具有一致错误 schema，至少记录 400、401、404、500）；弃用操作（标记 deprecated: true 并在描述中说明替代端点或迁移路径）；外部文档（复杂或领域特定操作通过 externalDocs 链接外部文档）；additionalProperties（对象 schema 显式设置 true 或 false）；字符串约束（字符串属性适当定义 minLength、maxLength 或 pattern）。
严重级别
- S1 CRITICAL：规范无效、安全方案缺失或损坏，或会导致代码生成失败。需立即修复。
- S2 HIGH：可能导致集成问题、安全弱点或客户端行为错误。发布前修复。
- S3 MEDIUM：设计不一致、缺少文档或偏离最佳实践。应予以处理。
- S4 LOW：风格建议、次要命名改进或可选增强。酌情处理。
输出格式
审查报告结构如下：摘要（2-3 句概述 API 描述内容、整体质量评估与最重要发现）；发现列表（每条包含严重级别、类别、标题、位置、问题说明与具体修复建议，按严重级别排序）；正面观察（1-3 项规范做得好的地方）；统计表（各严重级别的数量统计）。
适用场景与限制
适用于审查 OpenAPI 规范文件的结构合规性、安全性、设计实践与文档质量。审查时需具体引用确切的路径、属性名与 operationId，并提供带 YAML 或 JSON 片段的修复建议。对于内部一致的合法风格选择不应标记。对于超过 100 个路径的大型规范，会按标签或资源组划分审查并给出合并摘要。当不确定 API 领域意图时，会明确说明假设而非默默判断。该技能的具体安装方式、收费情况、平台支持等信息暂未提供。