Introduction to Spring REST Docs

1. 概述

Spring REST Docs为 RESTful 服务生成准确且可读的文档。它将手写文档与通过 Spring 测试生成的自动生成的文档片段相结合。

2、优点

该项目背后的一项主要理念是使用测试来生成文档。这可确保生成的文档始终与 API 的实际行为准确匹配。此外，输出已准备好由Asciidoctor处理，Asciidoctor 是一个以 AsciiDoc 语法为中心的发布工具链。这与用于生成 Spring 框架文档的工具相同。

这些方法减少了其他框架施加的限制。 Spring REST Docs 生成准确、简洁且结构良好的文档。然后，该文档使 Web 服务使用者能够轻松地获取他们所需的信息。

该工具还有其他一些优点，例如：

生成curl和http请求片段
轻松将文档打包到项目 jar 文件中
轻松向片段添加额外信息
同时支持 JSON 和 XML

生成片段的测试可以使用 Spring MVC 测试支持、Spring Webflux 的 WebTestClient 或 REST-Assured 来编写。

在我们的示例中，我们将使用 Spring MVC 测试，但使用其他框架非常相似。

3. 依赖关系

在项目中开始使用 Spring REST Docs 的理想方法是使用依赖管理系统。在这里，我们使用 Maven 作为构建工具，因此可以将以下依赖项复制并粘贴到您的 POM 中：

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.4.RELEASE</version>
</dependency>

您还可以在此处检查 Maven Central 是否有新版本的依赖项。

在我们的示例中，我们需要 spring-restdocs-mockmvc 依赖项，因为我们使用 Spring MVC 测试支持来创建测试。

如果我们想使用 WebTestClient 或 REST Assured 编写测试，我们将需要spring-restdocs-webtestclient和spring-restdocs-restassured依赖项。

4. 配置

如前所述，我们将使用 Spring MVC 测试框架向要记录的 REST 服务发出请求。运行测试会生成请求的文档片段和生成的响应。

我们可以将该库用于 JUnit 4 和 JUnit 5 测试。让我们看看每个所需的配置。

4.1. JUnit 4 配置

为 JUnit 4 测试生成文档片段的第一步是声明一个公共 JUnitRestDocumentation 字段，该字段注释为 JUnit @Rule 。

JUnitRestDocumentation 规则配置了生成的代码片段应保存到的输出目录。例如，该目录可以是 Maven 的构建目录：

@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");

接下来，我们设置 MockMvc 上下文，以便将其配置为生成文档：

@Autowired
private WebApplicationContext context;

private MockMvc mockMvc;

@Before
public void setUp(){
    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
      .apply(documentationConfiguration(this.restDocumentation))
      .build();
}

MockMvc 对象是使用 MockMvc RestDocumentationConfigurer 配置的。此类的实例可以从 org.springframework.restdocs.mockmvc.MockMvcRestDocumentation 上的静态 DocumentationConfiguration() 方法获取。

4.2. JUnit 5 配置

要使用 JUnit 5 测试，我们必须使用 RestDocumentationExtension 类扩展测试：

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
@SpringBootTest
public class ApiDocumentationJUnit5IntegrationTest { //... }

使用 Maven 时，此类会自动配置 /target/ generated-snippets 输出目录，或者使用 Gradle 时 ，会自动配置 /build/generate-snippets 。

接下来，我们必须在 @BeforeEach 方法中设置 MockMvc 实例：

@BeforeEach
public void setUp(WebApplicationContext webApplicationContext,
  RestDocumentationContextProvider restDocumentation) {
    this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
      .apply(documentationConfiguration(restDocumentation)).build();
}

如果我们不使用 JUnit 进行测试，那么我们必须使用 ManualRestDocumentation 类。

5. 安心服务

让我们创建一个可以记录的 CRUD RESTful 服务：

@RestController
@RequestMapping("/crud")
public class CRUDController {
    
    @GetMapping
    public List<CrudInput> read(@RequestBody CrudInput crudInput) {
        List<CrudInput> returnList = new ArrayList<CrudInput>();
        returnList.add(crudInput);
        return returnList;
    }
    
    @ResponseStatus(HttpStatus.CREATED)
    @PostMapping
    public HttpHeaders save(@RequestBody CrudInput crudInput) {
        HttpHeaders httpHeaders = new HttpHeaders();
        httpHeaders.setLocation(
          linkTo(CRUDController.class).slash(crudInput.getTitle()).toUri());
        return httpHeaders;
    }
    
    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") long id) {
        // delete
    }
}

然后，我们还添加一个 IndexController ，它返回一个页面，其中包含指向 CRUDController 基本端点的链接：

@RestController
@RequestMapping("/")
public class IndexController {

    static class CustomRepresentationModel extends RepresentationModel<CustomRepresentationModel> {
        public CustomRepresentationModel(Link initialLink) {
            super(initialLink);
        }
    }

    @GetMapping
    public CustomRepresentationModel index() {
        return new CustomRepresentationModel(linkTo(CRUDController.class).withRel("crud"));
    }
}

6.JUnit 测试

回到测试中，我们可以使用 MockMvc 实例来调用我们的服务并记录请求和响应。

首先， 为了确保每个 MockMvc 调用都会自动记录，无需任何进一步的配置，我们可以使用 alwaysDo() 方法 ：

this.mockMvc = MockMvcBuilders
  //...
  .alwaysDo(document("{method-name}", 
    preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint())))
  .build();

此设置可确保每次 MockMvc 调用时，都会在具有测试方法名称的文件夹中创建默认代码片段。此外，应用 PrettyPrint() 预处理器以更易于阅读的方式显示片段。

让我们继续自定义一些调用。

要记录包含链接的索引页，我们可以使用静态 links() 方法：

@Test
public void indexExample() throws Exception {
    this.mockMvc.perform(get("/")).andExpect(status().isOk())
      .andDo(document("index", 
        links(linkWithRel("crud").description("The CRUD resource")), 
        responseFields(subsectionWithPath("_links")
          .description("Links to other resources"))
        responseHeaders(headerWithName("Content-Type")
          .description("The Content-Type of the payload"))));
}

在这里，我们使用 linkWithRel() 方法来记录指向 /crud 的链接。

为了将 Content-Type 标头添加到响应中，我们使用 headerWithName() 方法对其进行记录，并将其添加到 responseHeaders() 方法中。

我们还使用 responseFields() 方法记录响应负载。 这可用于使用 subsectionWithPath() 或 fieldWithPath() 方法来记录响应的更复杂的子部分或单个字段。

与响应负载类似，我们也可以使用 requestPayload() 记录请求负载：

@Test
public void crudCreateExample() throws Exception {
    Map<String, Object> crud = new HashMap<>();
    crud.put("title", "Sample Model");
    crud.put("body", "http://www.baeldung.com/");
       
    this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON)
      .content(this.objectMapper.writeValueAsString(crud)))
      .andExpect(status().isCreated())
      .andDo(document("create-crud-example", 
        requestFields(fieldWithPath("id").description("The id of the input"),
          fieldWithPath("title").description("The title of the input"),
          fieldWithPath("body").description("The body of the input"),
        ))));
}

在此示例中，我们记录了 POST 请求，该请求接收带有标题和正文字段的 CrudInput 模型并发送 CREATED 状态。 每个字段都使用 fieldWithPath() 方法进行记录。

要记录请求和路径参数，我们可以使用 requestParameters() 和 pathParameters() 方法。 两种方法都使用 parameterWithName() 方法来描述每个参数：

@Test
public void crudDeleteExample() throws Exception {
    this.mockMvc.perform(delete("/crud/{id}", 10)).andExpect(status().isOk())
      .andDo(document("crud-delete-example", 
      pathParameters(
        parameterWithName("id").description("The id of the input to delete")
      )));
}

在这里，我们记录了接收 id 路径参数的删除端点。

Spring REST Docs 项目包含更强大的文档功能，例如可以在文档中找到的字段约束和请求部分。

7. 输出

构建成功运行后，将生成 REST 文档片段的输出并将其保存到 target/ generated-snippets 文件夹中：

生成的输出将包含有关服务的信息、如何调用 REST 服务（例如“curl”调用）、来自 REST 服务的 HTTP 请求和响应以及服务的链接/端点：

卷曲命令

----
$ curl 'http://localhost:8080/' -i
----

HTTP – REST 响应

[source,http,options="nowrap"]
----
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 93

{
  "_links" : {
    "crud" : {
      "href" : "http://localhost:8080/crud"
    }
  }
}
----

8. 使用代码片段创建文档

要在较大的文档中使用这些片段，您可以使用 Asciidoc include 引用它们。 在我们的例子中，我们在 src/docs 中创建了一个名为 api-guide.adoc 的文档：

在该文档中，如果我们希望引用链接片段，我们可以使用占位符 {snippets} 来包含它，该占位符在 Maven 处理文档时将被替换：

==== Links

include::{snippets}/index-example/links.adoc[]

9.Asciidocs Maven 插件

要将 API 指南从 Asciidoc 转换为可读格式，我们可以向构建生命周期添加 Maven 插件。有几个步骤可以实现此目的：

将 Asciidoctor 插件应用到 pom.xml
在 testCompile 配置中添加对 spring-restdocs-mockmvc 的依赖，如依赖项部分中所述
配置属性以定义生成的片段的输出位置
配置测试任务以将代码片段目录添加为输出
配置 asciidoctor 任务
定义一个名为 snippets 的属性，在文档中包含生成的片段时可以使用该属性
使任务依赖于测试任务，以便在创建文档之前运行测试
将片段目录配置为输入。所有生成的片段都将在此目录下创建

将代码片段目录添加为 pom.xml 中的属性，以便 Asciidoctor 插件可以使用此路径在此文件夹下生成代码片段：

<properties>
    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>

pom.xml 中用于从构建生成 Asciidoc 片段的 Maven 插件配置如下：

<plugin> 
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>package</phase> 
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <doctype>book</doctype>
                <attributes>
                    <snippets>${snippetsDirectory}</snippets> 
                </attributes>
                <sourceDirectory>src/docs/asciidocs</sourceDirectory>
                <outputDirectory>target/generated-docs</outputDirectory>
             </configuration>
     </execution>
    </executions>
</plugin>

10. API文档生成流程

当 Maven 构建运行并执行测试时，所有代码片段将在配置的 target/ generated-snippets 目录下的 snippets 文件夹中生成。生成代码片段后，构建过程会生成 HTML 输出。

生成的 HTML 文件已格式化且可读，因此 REST 文档可供使用。每次 Maven 构建运行时，也会生成包含最新更新的文档。

11. 结论

没有文档总比错误的文档好，但是 Spring REST 文档将有助于为 RESTful 服务生成准确的文档。

作为一个官方的 Spring 项目，它通过使用三个测试库来实现其目标：Spring MVC Test、 WebTestClient 和 REST Assured。这种生成文档的方法可以帮助支持测试驱动的方法来开发和记录 RESTful API。

您可以在链接的 GitHub 存储库中找到基于本文中的代码的示例项目。

Persistence

REST

Security