我应该使用什么规格记录REST API的？ [英] What specification should I use for documenting REST APIs?

问题描述

我一直在寻找自动创建一个项目，我工作的REST API的文档。首先，水润（ http://www.hydra-cg.com ）显示了一个有趣的想法设计Web的API。后来有同事建议我使用扬鞭2.0（ http://swagger.io ）为code发生器。然后，我意识到，这两种规格可以解决记录了REST API的同样的问题。

I've been looking for automatic creating the documentation for the REST API of a project I'm working on. First, 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) as code generator. Then, I realise that both specifications can solve the same problem of documenting the REST API.

什么缺点/使用水润或扬鞭规范的好处是什么？

What are the downsides/benefits of using Hydra or Swagger specification?

谢谢！

推荐答案

扬鞭是公认的，并支持广泛的语言和框架。它不会强迫你写的API在一个特定的风格，它应该是更好的选择，如果你只是想记录现有的API。

Swagger is well established and supports a wide range of languages and frameworks. It doesn't force you to write the API in a specific style and it should be a better fit if you just want to document an existing API.

水润看起来很有希望，但还没有被任何标准组织和行业采用，使其真正的标准。它由一个工作组只是一个非正式的草案现在。它似乎也很新和PHP和Java，不能用于生产只提供了一些实验工具。我甚至不知道你是否可以在不显著改变API与现有的API框架结合起来。

Hydra looks promising but has yet to be adopted by any standards organizations and the industry to make it a real standard. It's just an unofficial draft by a working groups for now. It also seems very new and provides only a few experimental tools for php and java, not ready for production. I'm not even sure if you can integrate the framework with an existing API without changing the API significantly.

正如inf3erno指出，Hydra是更侧重于的REST服务的原始定义。在乍看之下，似乎对我说，他们使用的是类似于 HATEOAS 原则，并尝试了形式化技术使用的词汇。我认为有充分的理由，虽然留的REST服务的现代定义，不加HATEOAS或词汇使发展变得复杂。

As stated by inf3erno, Hydra is more focused on the original definition of REST services. On a first glance it seems to me that they are using principles similar to HATEOAS and try to formalize that technique using vocabularies. I think there is good reason to stay with the modern definition of REST services though and don't make development to complicated by adding HATEOAS or vocabularies.

这篇关于我应该使用什么规格记录REST API的？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！