我一直在寻找为我正在处理的项目的 REST API 自动创建文档。首先，Hydra (http://www.hydra-cg.com) 提出了一个设计 Web API 的有趣想法。后来有同事推荐我使用 Swagger 2.0 (http://swagger.io) 作为代码生成器。然后，我意识到这两个规范都可以解决记录 REST API 的同一个问题。
使用 Hydra 或 Swagger 规范有哪些缺点/好处？
谢谢！！！
【问题讨论】：
标签： api rest jax-rs swagger hydra-core
Swagger 非常成熟，支持多种语言和框架。它不会强迫您以特定样式编写 API，如果您只想记录现有 API，它应该更适合。
Hydra 看起来像是开发 REST API 的有趣框架，但尚未被任何标准组织和采用以使其成为真正的标准。目前这只是一个 W3C 社区团体的非官方草案。它似乎也很新，并为某些似乎还没有准备好投入生产的语言提供实验性工具。我什至不确定您是否可以在不显着更改 API 的情况下将该框架与现有 API 集成。
正如 inf3erno 所述，Hydra 更关注 REST 服务的原始定义，生成的文档只是一个副产品。乍一看，在我看来，他们正在使用类似于HATEOAS 的原则，并尝试使用词汇表形式化该技术。我认为有充分的理由保留 REST 服务的更简单的现代定义，并且不要通过添加 HATEOAS 或词汇表使开发变得复杂。
【讨论】：
Hydra 是关于创建一个特定于 REST 的词汇，因此在它成为标准之后，每个 REST API 都可以使用该词汇，并且可以编写通用的 REST 客户端，就像浏览器目前是为网络上的人类用户服务一样。那是真正的 REST。当前所谓的 REST API 不满足统一接口约束，因为它们使用非标准解决方案。九头蛇将解决这个问题。这只是一个无关紧要的细节，如果使用 hydra 术语进行描述，则可以从 API 特定词汇生成文档。
不知道什么是招摇，但它似乎是同一问题的非标准解决方案。
【讨论】：