验证 OpenAPI 是否符合 REST 设计最佳实践

Question

我们使用 Swagger 从源代码生成 API 文档。我现在想知道是否有任何工具可以自动检查生成的 OpenAPI 文档（= Swagger JSON）是否符合 RESTful API 设计最佳实践。

\n\n

例如，Zalando 定义了一个公开的 REST 设计指南，我认为这些指南中有许多规则可以根据 OpenAPI 规范自动检查：

\n\n

\n
• \xe2\x80\x9cDon\xe2\x80\x99t 破坏向后兼容性\xe2\x80\x9d 可以在比较不同版本的 OpenAPI 文档时检查到。
\n
• \xe2\x80\x9c始终返回 JSON 对象作为顶级数据结构以支持\n可扩展性”
\n
• 如果与字典相比，\xe2\x80\x9cKeep URLs Verb-Free\xe2\x80\x9d 可能会被检查。
\n
• \xe2\x80\xa6
\n

\n\n

到目前为止，我只找到了检查 OpenAPI 文档的完整性和命名约定的工具。有人知道具有更高级规则的工具吗？

\n\n

更新：

\n\n

同时我发现了一个名为 Zally 的工具（https://github.com/zalando-incubator/zally）。该工具检查是否违反 Zalando 的 REST-Api 指南。配置或扩展相当容易。

\n

Answer 1

其中一些可以作为规则添加到openapilint. 向后兼容性检查需要比较两个规范版本以寻找差异，这有点复杂。