我一直在考虑一个文档工具，用于为要在多个客户端中使用的 Web 服务构建后端，以及 OAuth 和多个修订的可能性。我已经知道养蜂场了，但做了一些研究，我发现了其他相当不错的解决方案，并承诺有利可图。
RAML 似乎承诺良好的代码生成和 api 可重用性。但它似乎无法创建模拟服务器。而且我不明白为什么 apiblueprint 不能用于为 REST API 生成客户端库和服务器端骨架。
对我们来说，最好的用例是 API 文档，可以自动生成用于使用服务的客户端 iOS/Android/wp/js 库以及提供框架以编写代码的 node express/restify 应用程序。连同 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, AngularJS with Google Closure Compiler annotations) 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 (Flask), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)
API 文档生成器：HTML、Confluence Wiki
免责声明：我是开源项目的主要贡献者之一。
更新：2018 年 5 月，Swagger Codegen 的大约 50 位顶级贡献者和模板创建者决定分叉 Swagger Codegen 以维护一个名为OpenAPI Generator的社区驱动版本。请参阅问答以获取更多信息。
免责声明：我为 Apiary 工作
我不认为这是一个好主意。
您对模拟服务器的需求暗示您已经接受了在实现之前描述的路径，这很好。
然而，这个想法是，一旦针对模拟服务器进行开发，您就可以迭代 API 设计（这就是为什么在“文本”工具而不是代码中这样做有意义的原因之一）......这是困难的部分.
有一些新兴的工具支持脚手架，但真正的问题是如何在蓝图更新后更新脚手架的应用程序。我知道有些人正在解决这个问题，但他们还没有被释放。
在我看来，最好的方法是针对模拟 API 开发真正的原型，以测试生成的应用程序的用户体验。一旦设计相当稳定，您就开始开发其他客户端以及服务器，最终扩展原始设计。
您可以使用在各自语言中找到的各自工具对它们进行测试，因为它们最适合给定的用例。要测试该实现是否符合蓝图（也称为书面合同），您可以使用dredd。
在此基础上进行协作的任何工具都应将蓝图作为输入，而不是生成无法维护的手动扩展库。
RAML确实提供了一个集成的、免费的、托管的模拟服务，您可以通过在API Designer中单击一个按钮来部署它。一旦您启用了模拟，try-it 将立即在集成的 API 控制台中启用，您可以使用插入到 RAML 文件中的 baseURI 进一步练习模拟的 API。
此外，我们将在不久的将来开源其他服务器框架（我们已经有 Mule 和 JAX-RS 框架）（包括 Node）。客户端生成有点远，但很快就会出现（首先是javascript，然后是其他的）。
披露：我积极参与 RAML 计划，并在 MuleSoft 担任我们开发的许多 RAML 工具的产品经理。
如果 RAML 控制台不够轻量级，您可能会发现https://github.com/kevinrenskers/raml2html非常有用且易于上手。
它不包含 RAML 控制台的所有功能（例如 Try out，用于从那里测试 API），但仍然是一个很棒的文档工具。