LOCAL API CONTRACT AUDIT

OpenAPI / Swagger 结构检查

检查 OpenAPI 3.0、3.1 与 Swagger 2.0 的 YAML/JSON，整理接口、路径参数、响应、Schema 和引用。它专注可解释的发布前预检，不会请求真实 API，也不会把规范上传服务器。

规范源码

0 字符 · YAML / JSON

粘贴或上传 OpenAPI / Swagger YAML、JSON 后运行结构检查。

结构预检不是完整合规认证

页面会检查最常见且可解释的问题，但不会下载外部 $ref，也没有把某一版官方 JSON Schema 和所有扩展打包进来。发布流水线仍应锁定 Swagger Parser、Redocly、Spectral 等项目级工具版本。

接口清单不能替代真实请求测试

cURL 使用规范里的第一个 server，并用占位符代替路径参数。认证、真实请求体、查询参数、网络策略和业务响应都要在测试环境继续验证。

OpenAPI 也需要版本审查

规范能通过解析，不代表描述与服务端一致。尤其要检查废弃接口、错误码、分页、幂等、权限、示例数据和 nullable/oneOf 等客户端生成器容易产生差异的部分。

RELATED TOOLS

接着处理

查看全部工具 →
YAML / JSON 转换先修复或转换规范文件的基础语法。JSON Schema 校验单独验证接口请求与响应使用的数据模型。cURL 转 Fetch把接口清单中的 cURL 转成前端请求代码。JSON 格式化格式化接口示例、响应和配置片段。

USE & REVIEW

OpenAPI / Swagger 结构检查常见问题

查看全部工具指南 →

OpenAPI / Swagger 文件会上传或执行接口请求吗？

不会。YAML/JSON 解析、路径与引用检查、接口清单和 cURL 草稿都在当前浏览器完成。工具不会下载外部 $ref，也不会向 servers 中的地址发请求；规范里若含内部域名或示例凭证，导出报告前仍要人工检查。

为什么页面称为“结构检查”，不是完整官方校验？

工具重点检查版本、info、paths、operationId、路径参数、responses 和本地 JSON Pointer 等高频问题，但没有把每个 OpenAPI 版本的完整官方 Schema、所有扩展和外部文件解析链打包进页面。CI 中仍应使用项目锁定版本的 Swagger Parser、Redocly、Spectral 或同类工具。

支持 OpenAPI 3.0、3.1 和 Swagger 2.0 吗？

可以解析并检查 OpenAPI 3.0.x、3.1.x 与 Swagger 2.0 的常见结构。其他版本会给出兼容性提示；厂商扩展 x-* 会保留，但页面不会理解每个扩展的业务规则。规范化 YAML/JSON 也可能改变注释、键顺序和原始格式。

路径参数会检查哪些错误？

工具会比较 /orders/{id} 里的模板名称与路径级、操作级 parameters，检查是否存在同名 in: path 参数，以及 required 是否为 true；还会提示声明了但路径中没有使用的参数。通过这些检查不代表参数 schema、格式和实际服务端行为完全一致。

外部 $ref 为什么只提示而不自动下载？

外部引用可能需要认证、相对文件目录、网络权限和组织内部地址。浏览器页面擅自抓取会带来隐私、CORS 与版本一致性问题，因此只验证当前文档内的 #/ 引用。项目构建时应从仓库根目录解析完整引用树，并锁定依赖文件。

生成的 cURL 可以直接用于生产接口吗？

它只是根据第一个 server、方法、路径和是否有请求体生成的草稿，路径参数会写成占位符。认证 Header、查询参数、真实 JSON、Cookie、证书、幂等键和环境地址都需要人工补充，并且只应先在受控测试环境执行。