我应该使用什么规范来记录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客户端，就像浏览器当前用于Web上的人类用户一样。这是真正的REST。当前所谓的REST API不能实现统一的接口约束，因为它们使用非标准的解决方案。 Hydra将解决这个问题。它只是一个微不足道的细节，如果用hydra术语描述，可以从API特定词汇生成文档。

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