比较Java REST文档框架

确定在记录REST API时选择哪种Java框架可能很麻烦。在本博文中，我们将简要比较我们自己使用的REST Web服务的三种文档框架，以及它们如何与Spring框架（这是Foreach最常使用的Java框架）集成。这些是RESTful API建模语言（RAML），Swagger 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）我们可以轻松地将其与所有其他非技术性文档结合在一起。