在 Spring 应用程序中为 HTTP 端点生成文档的过程

本指南将引导您完成在 Spring 应用程序中为 HTTP 端点生成文档的过程。

您将构建什么

您将构建一个简单的 Spring 应用程序，其中包含一些公开 API 的 HTTP 端点。您将使用 JUnit 和 Spring 的 仅测试 Web 图层。然后，您将使用相同的测试通过以下方式生成 API 的文档MockMvc春季休息文档.

你需要什么

• 约15分钟
• 最喜欢的文本编辑器或 IDE
• JDK 1.8或以后
• 格拉德尔 4+​或梅文 3.2+
• 您也可以将代码直接导入到 IDE 中：

• 弹簧工具套件 （STS）
• 智能理念
• VSCode

如何完成本指南

像大多数春天一样入门指南，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。无论哪种方式，您最终都会得到工作代码。

要从头开始，请继续从 Spring 初始化开始.

要跳过基础知识，请执行以下操作：

• 下载​并解压缩本指南的源存储库，或使用吉特:git clone https://github.com/spring-guides/gs-testing-restdocs.git
• 光盘成gs-testing-restdocs/initial
• 跳转到创建简单的应用程序.

完成后，您可以根据 中的代码检查结果。​​gs-testing-restdocs/complete​​

从 Spring 初始化开始

你可以使用这个预初始化项目，然后单击生成以下载 ZIP 文件。此项目配置为适合本教程中的示例。

手动初始化项目：

1. 导航到https://start.spring.io.此服务拉入应用程序所需的所有依赖项，并为您完成大部分设置。
2. 选择 Gradle 或 Maven 以及您要使用的语言。本指南假定您选择了 Java。
3. 单击“依赖关系”，然后选择“Spring Web”。
4. 单击生成。
5. 下载生成的 ZIP 文件，该文件是配置了您选择的 Web 应用程序的存档。

创建简单的应用程序

为您的 Spring 应用程序创建一个新控制器。以下清单（来自 ）显示了如何执行此操作：​​src/main/java/com/example/testingrestdocs/HomeController.java​​

package com.example.testingrestdocs;

import java.util.Collections;
import java.util.Map;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HomeController {

  @GetMapping("/")
  public Map<String, Object> greeting() {
    return Collections.singletonMap("message", "Hello, World");
  }

}

运行应用程序

Spring 初始化器创建一个可用于启动应用程序的类。下面的清单（来自）显示了 Spring 初始化器创建的应用程序类：​​main​​​​src/main/java/com/example/testingrestdocs/TestingRestdocsApplication.java​​

package com.example.testingrestdocs;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class TestingRestdocsApplication {

  public static void main(String[] args) {
    SpringApplication.run(TestingRestdocsApplication.class, args);
  }
}

​​@SpringBootApplication​​是一个方便的注释，它添加了以下所有内容：

• ​​@Configuration​​：将类标记为应用程序上下文的 Bean 定义源。
• ​​@EnableAutoConfiguration​​：告诉 Spring 引导根据类路径设置、其他 bean 和各种属性设置开始添加 bean。
• ​​@EnableWebMvc​​：将应用程序标记为 Web 应用程序并激活关键行为，例如设置 .Spring Boot 在看到类路径时会自动添加它。DispatcherServletspring-webmvc
• ​​@ComponentScan​​：告诉 Spring 在包中查找其他组件、配置和服务，让它找到类。com.example.testingrestdocsHelloController

该方法使用 Spring Boot 的方法启动应用程序。您是否注意到没有一行 XML？也没有文件。此 Web 应用程序是 100% 纯 Java，您无需处理配置任何管道或基础结构。Spring Boot为您处理所有这些。​​main()​​​​SpringApplication.run()​​​​web.xml​​

将显示日志记录输出。该服务应在几秒钟内启动并运行。

测试应用程序

现在应用程序正在运行，您可以对其进行测试。您可以在 上加载主页。但是，为了让自己更确信应用程序在您进行更改时可以正常工作，您需要自动执行测试。您还希望发布 HTTP 端点的文档。您可以使用 Spring REST 文档生成该测试的动态部分作为测试的一部分。​​http://localhost:8080​​

您可以做的第一件事是编写一个简单的健全性检查测试，如果应用程序上下文无法启动，该测试将失败。为此，请在测试范围内将 Spring Test 和 Spring REST 文档作为依赖项添加到项目中。以下清单显示了使用 Maven 时要添加的内容：

<dependency>
  <groupId>org.springframework.restdocs</groupId>
  <artifactId>spring-restdocs-mockmvc</artifactId>
  <scope>test</scope>
</dependency>

以下清单显示了已完成的文件：​​pom.xml​​

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.0</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <groupId>com.example</groupId>
  <artifactId>demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>gs-testing-restdocs</name>
  <description>Demo project for Spring Boot</description>
  <properties>
    <java.version>17</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- tag::test[] -->
    <dependency>
      <groupId>org.springframework.restdocs</groupId>
      <artifactId>spring-restdocs-mockmvc</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- end::test[] -->
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.8</version>
        <executions>
          <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <backend>html</backend>
              <doctype>book</doctype>
            </configuration>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
          </dependency>
        </dependencies>
      </plugin>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

以下示例显示了在使用 Gradle 时要添加的内容：

testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

以下清单显示了已完成的文件：​​build.gradle​​

plugins {
  id 'java'
  id 'org.springframework.boot' version '3.0.0'
  id 'io.spring.dependency-management' version '1.1.0'
  id 'org.asciidoctor.convert' version '1.5.8'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
  mavenCentral()
}

ext {
  set('snippetsDir', file("build/generated-snippets"))
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
  // tag::test[]
  testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
  // end::test[]
}

tasks.named('test') {
  outputs.dir snippetsDir
  useJUnitPlatform()
}

tasks.named('asciidoctor') {
  inputs.dir snippetsDir
  dependsOn test
}

现在创建一个带有 and 注释和空测试方法的测试用例，如以下示例 （from ） 所示：​​@RunWith​​​​@SpringBootTest​​​​src/test/java/com/example/testingrestdocs/TestingRestdocsApplicationTests.java​​

package com.example.testingrestdocs;

import org.junit.jupiter.api.Test;

import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class TestingRestdocsApplicationTests {

  @Test
  public void contextLoads() throws Exception {
  }
}

可以在 IDE 中或在命令行上运行此测试（通过运行 或 ）。​​./mvnw test​​​​./gradlew test​​

进行健全性检查是件好事，但您还应该编写一些测试来断言我们应用程序的行为。一个有用的方法是只测试 MVC 层，Spring 处理传入的 HTTP 请求并将其交给控制器。为此，您可以使用 Spring 的，并使用测试用例上的注释来请求为您注入它。以下示例（来自 ）演示了如何执行此操作：​​MockMvc​​​​@WebMvcTest​​​​src/test/java/com/example/testingrestdocs/WebLayerTest.java​​

@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
public class WebLayerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/"))
            .andExpect(status().isOk())
            .andExpect(content().string(containsString("Hello, World")));
    }
}

生成文档代码段

上一节中的测试发出（模拟）HTTP 请求并断言响应。您创建的HTTP API具有动态内容（至少在原则上），因此能够监视测试并抽取HTTP请求以在文档中使用真是太好了。Spring REST Docs 允许您通过生成“片段”来做到这一点。您可以通过向测试添加注释和额外的“断言”来使其工作。以下示例（来自 ）显示了完整的测试：​​src/test/java/com/example/testingrestdocs/WebLayerTest.java​​

package com.example.testingrestdocs;

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void shouldReturnDefaultMessage() throws Exception {
    this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())
        .andExpect(content().string(containsString("Hello, World")))
        .andDo(document("home"));
  }
}

新的注释是（来自 Spring Boot），它为生成的代码片段的目录位置获取参数。新的断言是 ，它为片段的字符串标识符获取参数。​​@AutoConfigureRestDocs​​​​MockMvcRestDocumentation.document​​

运行测试，然后查看 。您应该找到一个名为（标识符）的目录，其中包含​​target/snippets​​​​home​​阿斯科医生代码段，如下所示：

└── target
    └── snippets
        └── home
            └── curl-request.adoc
            └── http-request.adoc
            └── http-response.adoc
            └── httpie-request.adoc
            └── request-body.adoc
            └── response-body.adoc

默认代码段采用 HTTP 请求和响应的 Asciidoctor 格式。还有 和 的命令行示例（两个常见和流行的命令行 HTTP 客户端）。​​curl​​​​httpie​​

您可以通过向测试中的断言添加参数来创建其他代码段。例如，您可以使用代码段记录 JSON 响应中的每个字段，如以下示例 （from ） 所示：​​document()​​​​PayloadDocumentation.responseFields()​​​​src/test/java/com/example/testingrestdocs/WebLayerTest.java​​

this.mockMvc.perform(get("/"))
    ...
    .andDo(document("home", responseFields(
        fieldWithPath("message").description("The welcome message for the user.")
    ));

如果运行测试，则应找到一个名为 的附加代码段文件。它包含字段名称和描述的表。如果省略字段或将其名称弄错，则测试将失败。这就是 REST Docs 的强大功能。​​response-fields.adoc​​

使用代码段

若要使用生成的代码段，需要在项目中包含一些 Asciidoctor 内容，然后在生成时包含这些代码段。要查看此工作，请创建一个名为的新文件，并根据需要包含代码片段。以下示例（来自 ）演示了如何执行此操作：​​src/main/asciidoc/index.adoc​​​​src/main/asciidoc/index.adoc​​

= Getting Started With Spring REST Docs

This is an example output for a service running at http://localhost:8080:

.request
include::{snippets}/home/http-request.adoc[]

.response
include::{snippets}/home/http-response.adoc[]

As you can see the format is very simple, and in fact you always get the same message.

这个 Asciidoc 文件的主要特点是它通过使用 Asciidoctor 指令（冒号和尾随括号告诉解析器在这些行上做一些特殊的事情）包含两个片段。请注意，包含的代码段的路径表示为名为 的占位符（在 Asciidoctor 中为 ）。在这个简单的情况下，唯一的其他标记是代码片段顶部（这是一级部分标题）和标题之前（“请求”和“响应”）。将把该行上的文本转换为标题。​​include​​​​attribute​​​​{snippets}​​​​=​​​​.​​​​.​​

然后，在构建配置中，您需要将此源文件处理为您选择的文档格式。例如，您可以使用 Maven 生成 HTML（在您这样做时生成）。以下清单显示了该文件的 Asciidoc 部分：​​target/generated-docs​​​​./mvnw package​​​​pom.xml​​

如果使用 Gradle，则在运行 时生成。以下清单显示了该文件的 Asciidoctor 相关部分：​​build/asciidoc​​​​./gradlew asciidoctor​​​​build.gradle​​

plugins {
    ...
    id 'org.asciidoctor.convert' version '1.5.6'
}

...

asciidoctor {
    sourceDir 'src/main/asciidoc'
    attributes \
      'snippets': file('target/snippets')
}

总结

祝贺！您刚刚开发了一个 Spring 应用程序，并使用 Spring Restdocs 对其进行了记录。您可以将创建的 HTML 文档发布到静态网站，也可以将其打包并从应用程序本身提供。您的文档将始终是最新的，如果不是，测试将使您的构建失败。