| name | swagger-doc-validator |
| description | Validates a Swagger 2.0 YAML/JSON spec (or a validator error log) against the Swagger 2.0 specification, then emits a structured report (JSON + Markdown) with stable rule IDs and ready-to-paste YAML fix snippets. Use when the user provides an existing Swagger doc to review, a Swagger Editor error log to explain, or asks to verify a spec before shipping. |
Swagger Doc Validator (Swagger 2.0)
When To Use
Use when the user hands you:
- 一份已有的 Swagger 2.0 YAML/JSON，让你 review / 校验
- Swagger Editor 或
swagger-cli validate 的报错日志，让你解释并给修复
- 写完 spec 后的自查需求
触发短语：
- "帮我检查这份 swagger"
- "validate this swagger yaml"
- "这段 spec 报错了：responses.200 ..."
- "生成 swagger 校验报告"
如果用户是从 0 写一份新 spec，请改用 swagger-doc-writer。
校验清单（按顺序执行）
无需"真的调用工具"，但按固定顺序跑逻辑检查，保证输出稳定。
阻断型（error — 会导致 spec 不可校验）
- 版本与顶层结构：
swagger: "2.0" 存在；info, paths 存在
- paths & methods：使用的 method key ∈ {get, post, put, delete, patch, options, head}
- path param 一致性：
/x/{id} 必须在 parameters 里存在 in: path, name: id, required: true
- body 参数：
in: body 必须用 schema:，不能用 type:
- responses.description：每个状态码必须有
description
- $ref 有效性：所有
$ref 必须指向存在的 #/definitions/...
- security 引用：
security 中每个 scheme 名必须在 securityDefinitions 里存在
in 字段取值：必须 ∈ {path, query, header, body, formData}
质量型（warning — 能过但影响可用性）
- operationId：缺失建议补上（客户端生成强需求）
- tags：缺失建议补上（Swagger UI 分组）
- 错误码覆盖：GET 至少覆盖
400/401/404/500；POST/PUT/DELETE 再加 403/409
- default 响应：没有
default 时建议补兜底
- 枚举/约束：string 字段建议补
enum/pattern（如 phase 字段）；integer 建议补 minimum/maximum
- example：关键字段缺
example 影响 Swagger UI 可读性
OpenAPI 3 混写检测（高频坑）
components: / openapi: 3.x 这类字段出现在 swagger: "2.0" spec 中 → error，提示切换或重写requestBody 出现 → error（OpenAPI 3 语法），Swagger 2.0 用 in: body parameternullable: true → Swagger 2.0 不支持，用 x-nullable 或重构
规则编号表（rule.id，保持稳定）
| ID | 描述 |
|---|
SW2_VERSION_REQUIRED | 缺 swagger: "2.0" |
SW2_INFO_REQUIRED | 缺 info 或其必填子字段 |
SW2_PATHS_REQUIRED | 缺 paths |
SW2_RESP_DESCRIPTION_REQUIRED | responses[status].description 缺失 |
SW2_PATH_PARAM_REQUIRED_TRUE | in: path 参数未标 required: true |
SW2_PATH_PARAM_NAME_MATCHES_TEMPLATE | path 模板 {id} 与 parameters 对不上 |
SW2_BODY_PARAM_MUST_USE_SCHEMA | in: body 用了 type: 而非 schema: |
SW2_REF_DEFINITION_NOT_FOUND | $ref 指向不存在的 definition |
SW2_SECURITYDEFS_NAME_NOT_FOUND | security 引用未定义的 scheme |
SW2_IN_FIELD_INVALID | in: 值不在允许范围 |
SW2_METHOD_INVALID | path 下用了非法 method key |
SW2_OAS3_LEAKED_COMPONENTS | 混入 OpenAPI 3 的 components/requestBody/nullable |
SW2_OPERATIONID_MISSING | 缺 operationId（warning） |
SW2_TAGS_MISSING | 缺 tags（warning） |
输出格式（两种都给）
1. JSON 报告（机器可解析）
{
"swaggerVersionDetected": "2.0",
"isValid": false,
"summary": { "errorCount": 2, "warningCount": 1, "infoCount": 0 },
"checks": [
{
"severity": "error",
"category": "structure",
"message": "responses.200 is missing required field `description`",
"location": {
"jsonPath": "paths./models.get.responses.200",
"snippet": "200:\n schema: { $ref: \"#/definitions/ModelList\" }"
},
"rule": {
"id": "SW2_RESP_DESCRIPTION_REQUIRED",
"expected": "responses[statusCode].description must be present",
"actual": "missing"
},
"fix": {
"type": "add-field",
"suggestedChange": {
"path": "paths./models.get.responses.200.description",
"value": "成功返回 ModelDeployment 列表"
},
"replacementBlock": "\"200\":\n description: 成功返回 ModelDeployment 列表\n schema: { $ref: \"#/definitions/ModelList\" }"
}
}
],
"notes": []
}
字段约定：
category ∈ structure / reference / semantics / field-constraint / auth / yaml-parsefix.type ∈ replace-field / add-field / remove-field / rewrite-block / change-schema-ref / switch-auth-strategyreplacementBlock 给直接可粘贴的 YAML 片段
2. Markdown 报告（人读）
# Swagger 校验报告（Swagger 2.0）
- 是否通过：否
- 错误 / 警告：2 / 1
- 检测版本：2.0
## 结论摘要
- 阻断型：2 处（responses.description 缺失、path param 未标 required）
- 质量型：1 处（operationId 缺失）
- 优先修 **阻断型**，再处理质量型。
---
## 详细问题列表
### [E-001] responses.200 缺 description (`SW2_RESP_DESCRIPTION_REQUIRED`)
- 定位：`paths./models.get.responses.200`
- 类别：structure
- 原因：Swagger 2.0 要求每个 response 必须有 `description`
- 修复：
```yaml
"200":
description: 成功返回 ModelDeployment 列表
schema: { $ref: "#/definitions/ModelList" }
[E-002] path param 未声明 required (SW2_PATH_PARAM_REQUIRED_TRUE)
- 定位：
paths./models/{name}.get.parameters[0]
- 类别：structure
- 修复：添加
required: true
[W-010] 缺 operationId (SW2_OPERATIONID_MISSING)
- 定位：
paths./models.get
- 建议：补
operationId: listModels
复查清单
## Workflow
1. **拿到输入**：YAML 全文 or 错误日志 or 路径（则读取文件）
2. **解析 + 跑规则**：按"阻断型 → 质量型 → OAS3 混写"顺序扫
3. **构造报告**：JSON + Markdown 都输出（Markdown 给人读；JSON 便于后续自动化）
4. **排序**：error 在前（按 `rule.id` 稳定顺序），warning 在后
5. **给 fix**：每条 `error` 必须附 `replacementBlock`；warning 尽量给
6. **最后**：如果 spec 有大改（>5 处 error），建议用户用 `swagger-doc-writer` 基于现有信息重写骨架，而不是零碎 patch
## Output Checklist
- [ ] JSON 报告结构完整，`isValid` 准确反映是否还有 error
- [ ] Markdown 报告有"结论摘要 + 详细问题 + 复查清单"三段
- [ ] 每条 error 带 `rule.id` + `replacementBlock`
- [ ] path 模板与 parameters、`$ref` 的一致性检查都跑过
- [ ] 未触发的规则不要凑数写成 info
## Safety Checks
- **不要静默改用户的文件**：除非用户明确说"帮我直接改 yaml"，否则只输出报告和片段
- **区分 error vs warning**：只有阻断型才能让 `isValid: false`；风格/命名问题最多到 warning
- **OAS3 混写**：发现 `openapi: 3.x` 或 `components:` 时，**停止逐条校验**，优先提示用户决定是保留 2.0 还是迁移到 3.x，避免在错误版本上反复修
## Additional Resources
- Trigger phrases 与完整 I/O 示例：[examples.md](examples.md)
- 相关 skill：`swagger-doc-writer`（新建 spec）
- Swagger 2.0 规范：https://swagger.io/specification/v2/
