跳到正文

OpenAPI 检查

OpenAPI Linter

检查 OpenAPI 文档里缺失的响应、没人用的 schema、指不到东西的引用,以及别的会弄坏代码生成器的毛病。

检查一份 OpenAPI 3.0 或 3.1 文档里会弄坏代码生成器、让客户端库撒谎,或者规范干脆就要求的东西。规则是手写的,并列在页面上——是问题,不是风格偏好。

🔒 完全在你的浏览器里运行openapilintapiquality

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 的规则集。

接受 JSON 或 YAML 形式的 OpenAPI 3.0 和 3.1 文档。Swagger 2.0 得先升到 3。文档内部的 `$ref` 会跟进去;指向另一个文件的没法检查,只作为提示报出来。

想看两个版本之间改了什么,可以用 OpenAPI 变更比较。

怎么用

  1. 粘贴文档

    JSON 或 YAML,3.0 或 3.1。在这个标签页里解析;什么都不上传。

  2. 先处理错误

    每条发现带着规则 id 和它在文档里的精确位置。错误是真的会出问题的东西;警告是通常会出问题的东西。

  3. 某条发现让你意外时读规则列表

    每条规则都写明了严重级别和它存在的原因,所以一条你不同意的发现至少是一段你能读到的论证。

常见问题

它能加载我的 Spectral 规则集吗?

不能。这是一套固定的、手写的规则,为问题而选,不为团队风格。如果你有一份 Spectral 配置,Spectral 才是会遵守它的工具。

它不读我的 Swagger 2.0 文件。

对——2.0 是另一种文档形状,不是稍旧一点的 3.0,一半的规则对它都不适用。先转换;`swagger2openapi` 是常用的途径。

它没有跟进我的外部 `$ref`。

文档内部的 `$ref` 会解析;指向另一个文件的意味着从一个只有你机器上才有的路径抓取。它会作为一条备注报告,让你知道这项检查是不完整的,而不是干净的。

为什么缺 `operationId` 是警告?

因为生成器用它来给那个操作生成的函数命名。没有它,你得到一个从路径和方法派生的名字,路径一变它就变——你接口里的一次重命名会变成每个客户端里的一次重命名。

可以从这些接进来

接下来

这些工具吃得下当前工具的产出,结果可以直接送过去。