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