本页是使用 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。