良好的休息代码生成和文档工具

我一直在考虑一个文档工具,用于构建Web服务的后端,以便在多个客户端中使用OAuth以及多次修订的可能性.我已经知道了蜂房,但做了一些研究,我找到了其他相当好的解决方案,并且有利可图的承诺.

RAML似乎承诺良好的代码生成和api可重用性.但它似乎无法创建模拟服务器.我无法理解为什么apiblueprint不能用于生成REST API的客户端库和服务器端框架.

对我们来说最好的用例是基于api的文档,用于消费服务的客户端iOS/Android/wp/js库可以与节点快速/解析应用程序一起自动生成,该应用程序提供编写代码的框架.随着api测试和负载测试.

RAML/Swagger/Apiary中的哪种解决方案最适合这种情况？

请查看Swagger Codegen(免费,开源),它可以生成不同语言的服务器存根和API客户端.

许多公司/项目正在生产中使用它:https://github.com/swagger-api/swagger-codegen#companiesprojects-using-swagger-codegen

支持的语言/框架:

API客户端:ActionScript,Bash,C#(.net 2.0,4.0或更高版本),C++(cpprest,Qt5,Tizen),Clojure,Dart,Elixir,Go,Groovy,Haskell,Java(Jersey1.x,Jersey2.x,OkHttp ,Retrofit1.x,Retrofit2.x,Feign),Node.js(ES5,ES6,带有Google Closure Compiler注释的AngularJS)Objective-C,Perl,PHP,Python,Ruby,Scala,Swift(2.x,3.x) ),Typescript(Angular1.x,Angular2.x,Fetch,jQuery,Node)

服务器存根:C#(ASP.NET Core,NancyFx),Erlang,Go,Haskell,Java(MSF4J,Spring,Undertow,JAX-RS:CDI,CXF,Inflector,RestEasy),PHP(Lumen,Slim,Silex,Zend Expressive) ),Python的(烧瓶),的NodeJS,红宝石(屈,Rails5),斯卡拉(雀,Scalatra的)

API文档生成器:HTML,Confluence Wiki

免责声明:我是开源项目的主要贡献者之一.

更新:2018年5月,Swagger Codegen的大约50名顶级贡献者和模板创建者决定使用Swagger Codegen来维护一个名为OpenAPI Generator的社区驱动版本.有关更多信息,请参阅问答.

免责声明:我为Apiary工作

我不认为这是个好主意.

您对模拟服务器的需求提示您已经接受了实现前的描述路径,这很好.

但是,我的想法是,一旦针对模拟服务器进行开发,你就会迭代API设计(这就是为什么在"文本"工具而不是代码中执行它的原因之一)...... 这就是困难的部分.

有一些支持脚手架的新兴工具,但真正的问题是如何在蓝图更新后更新脚手架应用程序.我知道有些人正在解决这个问题,但他们尚未发布.

在我看来,最好的方法是针对模拟的API开发真实的原型,以测试生成的应用程序的用户体验.一旦设计相当稳定,您就开始开发其他客户端以及服务器,最终扩展原始设计.

您可以使用相应语言中的相应工具对它们进行测试,因为它们最适合特定用例.要测试该实现是否符合蓝图(即书面合同),您可以使用dredd.

任何在其上合作的工具都应该将蓝图作为输入,而不是生成库以手动扩展,这是不可能维护的.

RAML确实提供了一个集成的,免费的托管模拟服务,只需在API Designer中单击一下按钮即可部署.启用模拟后,将在集成的API控制台中立即启用试用,您可以使用插入RAML文件中的baseURI进一步练习模拟的API.

此外,我们将在不久的将来(包括Node)开放其他服务器框架(我们已经拥有Mule和JAX-RS框架).客户端生成稍微远一点,但也很快就会出现(首先是javascript,然后是其他人).

披露:我积极参与RAML计划,并为MuleSoft担任我们开发的许多RAML工具的产品经理.