OpenAPI 检查
OpenAPI Linter
检查 OpenAPI 文档里缺失的响应、没人用的 schema、指不到东西的引用,以及别的会弄坏代码生成器的毛病。
检查一份 OpenAPI 3.0 或 3.1 文档里会弄坏代码生成器、让客户端库撒谎,或者规范干脆就要求的东西。规则是手写的,并列在页面上——是问题,不是风格偏好。
OpenAPI 文档
拖入一个 openapi.yaml
只在这个标签页里读取。
24条结果
错误schema-array-itemscomponents.schemas.Order.items
`type: array` 却没有 `items`。
错误path-param-undeclaredGET /orders/{orderId}
路径里的 `{orderId}` 没有声明成参数。
错误response-descriptionGET /orders/{orderId}
`200` 响应没有 description。
错误schema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` 却没有 `items`。
错误info-missinginfo
没有 `info.version`。它是这个 API 的版本,不是 OpenAPI 的版本。
错误operation-id-duplicatePOST /orders/{orderId}
operationId `getOrder` 在 GET /orders/{orderId} 上也有。
错误path-param-requiredPOST /orders/{orderId}
`in: path` 参数 `id` 没有 `required: true`。
错误path-param-undeclaredPOST /orders/{orderId}
路径里的 `{orderId}` 没有声明成参数。
错误path-param-unusedPOST /orders/{orderId}
`in: path` 参数 `id` 没有出现在路径里。
警告path-trailing-slash/orders/
这条路径以 `/` 结尾。
警告schema-unusedcomponents.schemas.Customer
没有任何地方引用这个 schema。
警告operation-id-missingGET /orders/
没有 operationId。
警告response-errorGET /orders/
没有 4xx 响应。
警告description-missingGET /orders/{orderId}
summary 和 description 都没有。
警告response-errorGET /orders/{orderId}
没有 4xx 响应。
警告description-missingPOST /orders/{orderId}
summary 和 description 都没有。
警告response-errorPOST /orders/{orderId}
没有 4xx 响应。
警告response-successPOST /orders/{orderId}
没有 2xx 或 3xx 响应。
提示tag-missingGET /orders/
没有标签。
提示tag-missingGET /orders/{orderId}
没有标签。
提示parameter-descriptionPOST /orders/{orderId}
参数 `id` 没有 description。
提示response-default-onlyPOST /orders/{orderId}
唯一的响应是 `default`。
提示tag-missingPOST /orders/{orderId}
没有标签。
提示servers-missingservers
没有列出服务器,所以基准 URL 是 `/`。
OpenAPI
3.0.3
操作
3
错误
9
警告
9
提示
6
一套手写的规则。它挑的是让代码生成器卡住、让客户端库说谎、以及规范确实要求的东西——是问题,不是偏好。它不加载 Spectral 的规则集。
想看两个版本之间改了什么,可以用 OpenAPI 变更比较。
怎么用
粘贴文档
JSON 或 YAML,3.0 或 3.1。在这个标签页里解析;什么都不上传。
先处理错误
每条发现带着规则 id 和它在文档里的精确位置。错误是真的会出问题的东西;警告是通常会出问题的东西。
某条发现让你意外时读规则列表
每条规则都写明了严重级别和它存在的原因,所以一条你不同意的发现至少是一段你能读到的论证。
常见问题
它能加载我的 Spectral 规则集吗?
不能。这是一套固定的、手写的规则,为问题而选,不为团队风格。如果你有一份 Spectral 配置,Spectral 才是会遵守它的工具。
它不读我的 Swagger 2.0 文件。
对——2.0 是另一种文档形状,不是稍旧一点的 3.0,一半的规则对它都不适用。先转换;`swagger2openapi` 是常用的途径。
它没有跟进我的外部 `$ref`。
文档内部的 `$ref` 会解析;指向另一个文件的意味着从一个只有你机器上才有的路径抓取。它会作为一条备注报告,让你知道这项检查是不完整的,而不是干净的。
为什么缺 `operationId` 是警告?
因为生成器用它来给那个操作生成的函数命名。没有它,你得到一个从路径和方法派生的名字,路径一变它就变——你接口里的一次重命名会变成每个客户端里的一次重命名。
可以从这些接进来
JSON Schema 生成
JSON to JSON Schema
从一份或多份样例推断 JSON Schema,把见到的各种形态并起来。
JSON Schema 校验
JSON Schema Validator
用 JSON Schema 校验文档,每一处失败都带上它在实例里的路径。
curl 转代码
curl to Code
把一条 curl 命令转成 fetch、axios、Python requests、Go、PHP 或 PowerShell 代码。
OpenAPI 变更对比
OpenAPI Diff
比较两份 OpenAPI 文档,把破坏兼容的变更和纯粹新增的分开列。
接下来
这些工具吃得下当前工具的产出,结果可以直接送过去。
curl 转代码
curl to Code
把一条 curl 命令转成 fetch、axios、Python requests、Go、PHP 或 PowerShell 代码。
JSON Schema 校验
JSON Schema Validator
用 JSON Schema 校验文档,每一处失败都带上它在实例里的路径。
OpenAPI 变更对比
OpenAPI Diff
比较两份 OpenAPI 文档,把破坏兼容的变更和纯粹新增的分开列。
YAML 格式化与校验
YAML Formatter & Validator
统一 YAML 缩进并校验语法,把会让解析器崩掉的制表符和锚点错误标出来。
JSON ⇄ CSV 互转
JSON ⇄ CSV
把嵌套 JSON 按点路径列名拍平成列,或者从表格重新拼回对象。
JSON 对比
JSON Diff
按结构比较两份 JSON,忽略键的顺序,报出新增、删除和改动的路径。