苏州网站建设万户,微信群二维码大全网站,网站优化大赛,wordpress直播播放器确定在记录REST API时选择哪种Java框架可能很麻烦。 在本博文中#xff0c;我们将简要比较我们自己使用的REST Web服务的三种文档框架#xff0c;以及它们如何与Spring框架#xff08;这是Foreach最常使用的Java框架#xff09;集成。 这些是RESTful API建模语言#xff0… 确定在记录REST API时选择哪种Java框架可能很麻烦。 在本博文中我们将简要比较我们自己使用的REST Web服务的三种文档框架以及它们如何与Spring框架这是Foreach最常使用的Java框架集成。 这些是RESTful API建模语言RAMLSwagger UI和Spring REST Docs。 在每一部分中我们将对所讨论的文档框架进行高层概述。 我们将简要描述文档框架如何与Spring集成以及如何在您的文档中使用该框架影响构建周期。 RESTful API建模语言RAML RAML是一个单独的文档与您作为开发人员需要手动维护的项目一起保存。 在默认的RAML配置中几乎不会自动执行任何操作。 但是借助随附的插件生态系统很容易扩展RAML使其表现出所需的行为。 该文档框架的生态系统非常活跃其插件启用了各种功能例如 API Workbench “一个用于设计构建测试记录和共享RESTful HTTP API的丰富功能齐全的集成开发环境IDE” RAML Java客户端生成器 根据RAML文档自动生成Java客户端的工具 RAML2HTML 一种Node.js工具用于生成用户友好HTML文档。 在构建过程中定义的额外步骤中书面文档将从RAML格式转换为人类可读的文本或HTML。 过去RAML曾经是Java中我们首选的文档框架但是现在我们发现了一些替代方案因此开始越来越少地使用RAML。 另外使用RAML很难编写也易于使用的完整文档因为RAML中的所有文档都需要手动编写。 此外我们通常会在对API进行调整后忘记更新文档。 通过使用一个框架可以解决此问题在该框架中大多数API更改都是自动记录的而不是手动记录的。 招摇UI 相反Swagger UI会自动生成所有内容。 在此框架中Swagger与Swagger UI和Springfox协同工作以在运行时生成文档。 该框架包含三个组件 Swagger是规范的一部分一组描述RESTful服务的规则与RAML相当 Swagger UI是呈现部分它呈现用户友好HTML就像RAML2HTML一样并允许用户在没有任何客户端基础结构的情况下测试服务因为它会基于Swagger服务规范自动生成测试客户端 Springfox是“生成”部分它与服务交互通过注释包括它自己的注释和Spring注释以在运行时自动生成文档。 这三个组件将检查您的代码以确定需要记录的内容。 他们既可以生成文档通过动态网站也可以通过Swagger UI进行“测试服务调用”。 服务调用的工作方式与例如Postman相同唯一的区别在于该库可以通过从应用程序的文档化部分向服务发送原始请求来在浏览器中工作。 由于Springfox将在运行时负责生成因此无需定义额外的构建步骤与RAML和Spring REST Docs不同在其中需要单独的构建步骤。 当我们第一次开始使用它时Swagger堆栈似乎很棒。 我们几乎没有人工劳动因为一切都是自动生成的。 同时我们仍然可以通过在代码中添加注释来调整文档。 我们认为这既是优点也是缺点。 因为虽然Swagger UI确实易于使用但是我们对生成的文档的控制没有我们想要的那么多。 Spring REST文件 Spring REST Docs是Spring生态圈的一部分可根据您的单元测试生成AsciiDoc片段。 这些片段可以包含在手写的AsciiDoc中以为您的API汇编文档。 为此您可以指定希望从对MockMVC端点的调用中检索的字段并定义要在文件系统上创建生成的代码段的位置。 如果期望的字段与结果不完全一致则您的测试将失败这意味着与文档相关的单元测试也将作为代码的额外检查。 在构建过程的后期您将需要定义一个额外的步骤通过将生成的代码片段与手写索引页结合起来生成人类可读HTML文件从而促进文档的传播。 我们在一个项目中使用了Spring REST Docs该项目需要外部参与者使用API和常规文档。 他们使用自己的测试工具因此不希望为他们提供基于浏览器的界面来测试该界面。 我们之所以选择REST Docs框架是因为a它也可以成为我们集成测试的一部分并且b我们可以轻松地将其与所有其他非技术性文档结合在一起。 总览 如您所见“最佳”文档框架取决于您期望文档框架能够完成的工作。 如果您希望不需要大量的“静态”文档即如果可以自动生成所有内容则开箱即用即可轻松使用Swagger UI。 另一方面如果您需要提供单个文档或者只想对文档进行更多控制则最好使用RAML或Spring REST Docs之类。 而且已经证明与Spring REST Docs中的测试集成非常有用。 无论您选择什么每个单独的框架都足以以明确的方式将Web服务的合同传达给其他开发人员-这最终是这些框架的目标。 翻译自: https://www.javacodegeeks.com/2019/01/comparing-java-documentation-frameworks.html
