本页是使用 DevUtilities 在浏览器中对 OpenAPI 与 Swagger 文档进行 lint 的权威指南。阅读时可在上方粘贴规范，或跳转到下方主题。验证仅在本地进行 — 文档绝不会上传。lint 变绿后，再管道到 Kiota SDK Engine 查看就绪评分与 generate 命令预览。

OpenAPI Validator 是面向 OpenAPI 3 与 Swagger 2 JSON/YAML 的客户端 lint 工具。它报告 VALID、VALID WITH WARNINGS 或 INVALID，并提供带路径的诊断，便于在 SDK 生成或网关导入前修复阻塞项。

您将获得

• 解析 OpenAPI 3.x 与 Swagger 2 文档（JSON 或 YAML）
• 状态横幅：VALID / VALID WITH WARNINGS / INVALID
• 检查版本键、paths 覆盖、servers 以及常见结构问题
• 仅本地 lint — 适合内部 API 规范
• 可直接交接至 Kiota SDK Engine 做代码生成就绪检查

在以下情况使用此工具

• 需要在 Microsoft Kiota 或其他生成器前做快速预检
• CI 或 PR 清单要求对已提交规范做可读 lint
• 继承了 Swagger 2 文件，希望在 OpenAPI 3 工作前看到迁移警告
• 重复的 operationId 或损坏的 $ref 持续导致代码生成失败

在以下情况优先使用相关工具

• 需要完整的 Kiota 就绪评分、语言矩阵与 CLI 构建器 → Kiota SDK Engine
• 只需美化 JSON 载荷 → JSON Formatter
• 需要模拟响应数组 → JSON Generator

代码生成器（尤其是 Kiota）会在随意扫一眼 YAML 容易漏掉的结构问题上大声失败。请先在此 lint，再打开 Kiota SDK Engine 做生成器特定的就绪检查。

代码生成前需清除的阻塞项

• 重复或缺失的 operationId（方法命名冲突）
• 成功状态码上缺少或为空的 responses
• 指向 components 的无效或悬空 $ref
• 缺少 openapi/swagger 版本键或 paths 对象为空
• 循环 schema 引用（常在下一步的 Kiota 中暴露）

可延后处理的警告

• 缺少 servers[] — 客户端可能需要 --base-url 覆盖
• Swagger 2 迁移说明 — 新 API 请优先 OpenAPI 3
• 描述稀疏 — 属于文档质量，不是解析阻塞项

生成 SDK 前的首次演练。

1. 将 OpenAPI 3 或 Swagger 2 以 JSON 或 YAML 粘贴到输入面板。
2. 查看状态：VALID、VALID WITH WARNINGS 或 INVALID。
3. 修复诊断列表中的每一项错误 — 从 operationId、responses 与 $ref 失败开始。
4. 重新 lint，直到状态为 VALID 或仅剩可接受的警告。
5. 将清理后的规范管道到 Kiota SDK Engine，查看就绪评分、语言预览与 kiota generate 命令。
6. 提交修复后的文档，并可选择将此 lint 加入 PR 检查清单。

拉取请求合并的 OpenAPI 修改会在之后破坏夜间 SDK 重新生成。审阅者无法凭肉眼发现重复的 operationId。

此工具如何解决

1. 审阅时将 PR 的 OpenAPI 文档粘贴到验证器中。
2. 批准前要求 VALID（或仅保留已记录的警告）。
3. 在审阅线程中用诊断文本标出重复的 operationId 与损坏的 $ref。
4. 合并后，在 CI 中对同一文档运行 Kiota。

以人工节奏运行的 lint 门禁，捕获与生成器同类的失败 — 且不上传规范。

团队即将运行 kiota generate，希望确认文档不会因命名或 $ref 问题失败。

此工具如何解决

1. 在此 lint 文档直至清除 INVALID。
2. 管道到 Kiota SDK Engine 并查看 OpenAPI Readiness 评分。
3. 在 Kiota 诊断中修复剩余的 Kiota 特有问题（循环引用、nullable 风格）。
4. 就绪可接受后复制生成的 CLI 命令。

两步本地工作流：结构 lint → Kiota 就绪 → 在本机 generate。

较旧的 Swagger 2 JSON 仍在驱动网关。相关方希望在采用 Kiota 前先使用 OpenAPI 3。

此工具如何解决

1. 粘贴 Swagger 2 文档并记录迁移警告。
2. 修复会阻断任何转换器的结构 INVALID 问题。
3. 为新功能规划 OpenAPI 3 迁移；仅在仍受门禁约束时保留 Swagger 2。
4. 在 Kiota 前重新 lint OpenAPI 3 结果。

明确信号：Swagger 2 会带警告解析 — 新 SDK 工作请优先 OpenAPI 3。

生成器根据 operationId 命名客户端方法。重复会导致冲突。

发生原因

两个或多个操作共享同一 operationId，或在生成器要求处缺少 operationId。

诊断

在文档中搜索重复的 operationId 值。Kiota 与此 lint 工具都会标记冲突 — 打开 SDK 引擎前先在此修复。

修复

1. 为每个操作分配唯一的 operationId（动词 + 资源是常见模式）。
2. 删除编辑时复制进来、未使用的重复 paths。
3. 若为部分 SDK 做裁剪，应删除冲突 paths，而不是随意重命名生产 ID。

重命名后请重新 lint，并再次检查 Kiota 就绪 — 预览中的方法名会变化。

没有可用 responses 的操作会破坏类型化客户端生成。

发生原因

某个 path 操作省略了 responses，或成功 responses 的 content {} 为空且没有 schema。

诊断

检查每个操作的 responses 映射中的 200/201（或 default）条目，并确认 content schema 可解析。

修复

1. 至少添加一个带 application/json（或相关）媒体类型的成功 response。
2. 通过 $ref 将 content schema 指向 components.schemas，而不是留下空 content。
3. 当客户端必须处理错误时，记录错误 responses（4xx/5xx）— 省略时可能仍有警告。

无效的 $ref 指针会在 lint 与代码生成期间阻止 schema 解析。

发生原因

$ref 指向缺失的组件、使用了错误的 JSON Pointer，或形成了解析器无法展开的环。

诊断

沿着每个失败的 $ref 路径进入 components.schemas / parameters / responses。确认目标键存在且拼写一致。

修复

1. 修复或重新创建缺失的组件目标。
2. 将 $ref 字符串规范化为 #/components/... 指针。
3. 通过提取浅层 DTO 打破循环引用（接下来适用 Kiota 的循环引用指南）。

在修改文档前先解读横幅。

OpenAPI Validator 与 Kiota SDK Engine 互补。在此做结构健康 lint；用 Kiota 做生成器就绪、语言矩阵、端点选择与 CLI 命令导出。

• 在 VALID 之后将清理后的规范管道或粘贴到 Kiota SDK Engine。
• 对生成器强调的重复 operationId、循环 $ref 与 nullable 风格问题，使用 Kiota 诊断。
• 从 Kiota Generate 步骤复制 kiota generate — 文件输出仍通过本地 Kiota CLI 运行。
• 保持两款工具均在客户端运行，使内部 API 契约永不离开浏览器。

• 每个 OpenAPI PR 批准前都先 lint。
• 新 API 优先 OpenAPI 3；将 Swagger 2 视为带迁移警告的遗留格式。
• 保持 operationId 唯一且稳定 — 重命名会搅动已生成客户端。
• 始终为成功 responses 提供可解析的 schema。
• 打开 Kiota 前先清除 INVALID；随后用 Kiota 做生成器特定就绪检查。
• 本地路径已足够时，不要将内部规范上传到第三方 lint SaaS。