良好的休息代码生成和文档工具[关闭]

Posted 2023-02-19

【中文标题】良好的休息代码生成和文档工具[关闭]

【英文标题】：Good rest code generation and documentation tool [closed]

【发布时间】：2014-04-27 09:44:07

【问题描述】：

我一直在考虑一种文档工具，用于为要在多个客户端中使用的 Web 服务构建后端，以及 OAuth 和多个修订的可能性。我已经知道养蜂场，但做了一些研究，我发现了其他相当不错的 solutions 并承诺有利可图。

RAML 似乎有望实现良好的代码生成和 api 可重用性。但它似乎无法创建模拟服务器。而且我不明白为什么不能使用 apiblueprint 为 REST API 生成客户端库和服务器端骨架。

对我们来说最好的用例将是 API 的文档，用于使用服务的客户端 ios/android/wp/js 库可以与提供框架以编写代码的 node express/restify 应用程序一起自动生成。以及 api 测试和负载测试。

RAML/Swagger/Apiary 中的哪种解决方案最适合此问题？

【问题讨论】：

我想为 Angular 编写一个代码生成器来处理这个问题，但需要一些支持

javascript的代码生成器已经可用，这里使用github.com/mulesoft/api-console/blob/master/bower.json。

github.com/raml-org/raml-js-parser 请参阅 Readme.md 底部的“浏览器使用情况”。

api-console 不是轻而易举的。它缩小了将近一兆字节的代码。为了解析数据结构并将其转换为可折叠列表，他们认为有必要将 angular、bootstrap 和 jQuery 塞进他们的 vendor.js 文件和他们自己的代码中……圣牛。他们在某一时刻重新发明了日期对象并定义了自己的 forEach 方法。哦，还有一个可爱的功能，您可以让所有 RAML 依赖项和特征在客户端上构建，方法是让它从 !@#$ing 服务器请求更多文件。你认为有多少 Java 开发者会选择 perf 谋杀？

【参考方案1】：

请查看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（带有 Google Closure Compiler 注释的 ES5、ES6、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（Flask）、NodeJS、Ruby（Sinatra、Rails5）、Scala（Finch、Scalatra）

API 文档生成器：html、Confluence Wiki

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

更新：2018 年 5 月，Swagger Codegen 的大约 50 位***贡献者和模板创建者决定分叉 Swagger Codegen 以维护一个名为 OpenAPI Generator 的社区驱动版本。更多信息请参考Q&A。

【讨论】：

@bummi swagger codegen 是Swagger 生态系统的一部分。作者确实询问过它，但到目前为止没有人提供有关 swagger 或 swagger-codegen 的任何细节。这就是为什么我指出它是为了让其他有相同问题的人更清楚。

【参考方案2】：

免责声明：我为 Apiary 工作

我认为这不是一个好主意。

您对模拟服务器的需求暗示了您已经接受了在实现之前描述的路径，这很好。

但是，这个想法是，一旦针对模拟服务器进行开发，您就可以迭代 API 设计（这就是为什么在“文本”工具而不是代码中这样做有意义的原因之一）......并且 那是困难的部分。

有一些新兴的工具支持脚手架，但真正的问题是如何在蓝图更新后更新脚手架的应用程序。我知道有些人正在解决这个问题，但他们还没有被释放。

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

您可以使用在各自语言中找到的各自工具对它们进行测试，因为它们最适合给定的用例。要测试该实现是否符合蓝图（也称为书面合同），您可以使用dredd。

在此基础上进行协作的任何工具都应将蓝图作为输入，而不是生成无法维护的手动扩展库。

【讨论】：

您对脚手架问题的看法是正确的，但在达到良好的结构和代码生成器后似乎可以解决。使用 Java 编译时注释当然是可能的。很想了解更多！

问题是可以使用模拟 API 蓝图来自动生成具有适用于 iOS 和 android 文档的强类型库，以便可以测试 UX？蓝图中列出的信息是否足够？

此外，Blueprint API 的 1A 格式似乎很快就会支持安全性？

是的，有足够的信息来生成强类型库。不，由于我提到的原因，我们还没有这样做。

至于“安全”，这是不是说“身份验证”的花哨方式？这很快就会在 1B 中推出，它对可重用模式提供更广泛的支持。有关相关问题，请参阅 github.com/apiaryio/api-blueprint/issues/11。

【参考方案3】：

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

此外，我们将在不久的将来开源其他服务器框架（我们已经有 Mule 和 JAX-RS 框架）（包括 Node）。客户端生成有点远，但很快就会出现（首先是javascript，然后是其他）。

披露：我积极参与 RAML 计划，并在 MuleSoft 担任我们开发的许多 RAML 工具的产品经理。

【讨论】：

我还应该提到，RAML 规范旨在提供足够的信息来生成强类型、文档齐全的库。我们还支持通过 RAML 规范中的安全方案模式定义现代 API 中的大多数常见安全模式，包括自定义方法。

什么时候可以很快意味着 iOS 有什么路线图？

【参考方案4】：

如果 RAML 控制台不够轻巧，您可能会发现 https://github.com/kevinrenskers/raml2html 非常有用且易于上手。

它不包含 RAML 控制台的所有功能（例如 Try out，用于从那里测试 API），但仍然是一个很棒的文档工具。