api - 我应该使用什么规范来记录 REST API？

Question

我一直在寻找为我正在处理的项目的 REST API 自动创建文档。首先，Hydra ( http://www.hydra-cg.com ) 提出了一个设计 Web API 的有趣想法。后来一些同事推荐我使用 Swagger 2.0 ( http://swagger.io ) 作为代码生成器。然后，我意识到这两个规范都可以解决记录 REST API 的同一个问题。

使用 Hydra 或 Swagger 规范有什么缺点/好处？

谢谢！！！

Answer 1

Swagger 已经很成熟并且支持广泛的语言和框架。它不会强迫您以特定样式编写 API，如果您只想记录现有 API，它应该更适合。

Hydra 看起来像是开发 REST API 的有趣框架，但尚未被任何标准组织和行业采用以使其成为真正的标准。目前这只是 W3C 社区团体的非官方草案。它似乎也很新，并为某些似乎还没有准备好投入生产的语言提供实验性工具。我什至不确定您是否可以在不显着更改 API 的情况下将框架与现有 API 集成。

正如 inf3erno 所说，Hydra 更专注于 REST 服务的原始定义，生成的文档只是一个副产品。乍一看，在我看来，他们正在使用类似于HATEOAS的原则，并尝试使用词汇表将这种技术形式化。我认为有充分的理由保留 REST 服务的更简单的现代定义，并且不要通过添加 HATEOAS 或词汇表使开发变得复杂。

Answer 2

Hydra 是关于创建一个特定于 REST 的词汇，因此在它成为标准之后，每个 REST API 都可以使用该词汇，并且可以编写通用的 REST 客户端，就像当前浏览器是为网络上的人类用户提供的一样。那是真正的 REST。当前所谓的 REST API 不满足统一接口约束，因为它们使用非标准解决方案。九头蛇将解决这个问题。这只是一个无关紧要的细节，如果使用 hydra 术语进行描述，则可以从 API 特定词汇生成文档。

A 不知道什么是招摇，但它似乎是同一问题的非标准解决方案。