使用spring-restdocs-webtestclient为springboot的webflux生成接口文档

背景

之前项目中采用springMVC开发web接口时，使用spring-restdocs-mockmvc来配合测试案例生成ascii文档。但如果采用spring的webflux开发web接口，那么将无法再使用mockmvc进行接口测试。

本文简单讲述如何使用spring-restdocs-webtestclient来改造mockmvc的测试案例，并生成ascii文档。

本文并未记述ascii文档模板的使用。有兴趣的同学请自行搜索Springboot restDocs的相关内容。

修改pom

在pom中去除spring-restdocs-mockmvc引用，改为:

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-test</artifactId>
 <scope>test</scope>
</dependency>
<dependency>
 <groupId>io.projectreactor</groupId>
 <artifactId>reactor-test</artifactId>
 <scope>test</scope>
</dependency>
<dependency>
 <groupId>org.springframework.restdocs</groupId>
 <artifactId>spring-restdocs-webtestclient</artifactId>
 <version>2.0.5.RELEASE</version>
</dependency>

其他相关引用即插件引用不变。如，你仍然需要使用如下插件：

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-surefire-plugin</artifactId>
 <configuration>
 <includes>
 <include>**/*Documentation.java</include>
 </includes>
 </configuration>
</plugin>
<plugin>
 <groupId>org.asciidoctor</groupId>
 <artifactId>asciidoctor-maven-plugin</artifactId>
 <version>1.5.3</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.apache.maven.plugins</groupId>
 <artifactId>maven-resources-plugin</artifactId>
 <executions>
 <execution>
 <id>copy-resources</id>
 <phase>prepare-package</phase>
 <goals>
 <goal>copy-resources</goal>
 </goals>
 <configuration>
 <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
 <resources>
 <resource>
 <directory>${project.build.directory}/generated-docs</directory>
 </resource>
 </resources>
 </configuration>
 </execution>
 </executions>
</plugin>

准备一个测试用父类

我们先准备一个测试案例父类，用来引入必须的配置：

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class SpringRestDocApplicationTests {
 @Rule
 public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

 @Autowired
 protected WebTestClient webTestClient;

 @Before
 public void setUp() {
 //默认生成的文档片段
 Snippet[] defaultSnippets = new Snippet[]{
 CliDocumentation.curlRequest(),
 CliDocumentation.httpieRequest(),
 HttpDocumentation.httpRequest(),
 HttpDocumentation.httpResponse(),
 PayloadDocumentation.requestBody(),
 PayloadDocumentation.responseBody()};

 this.webTestClient = this.webTestClient.mutate()
 .filter(WebTestClientRestDocumentation.documentationConfiguration(this.restDocumentation)
 .snippets().withTemplateFormat(TemplateFormats.asciidoctor()).withEncoding("UTF-8")
 .withDefaults(defaultSnippets))
 .build();
 }
}

在测试案例中改造测试代码

在一个继承了SpringRestDocApplicationTests的测试案例类(命名规则注意遵循*Documentation)中，我们将具体的接口请求代码改造如下：

• 改造前：

this.mockMvc.perform(post("/xx/xx/xx")
 .contentType(MediaType.APPLICATION_JSON_UTF8).accept(MediaType.APPLICATION_JSON)
 .content(JSON.toJSONString(requestObject)))
 .andExpect(status().isOk())
 .andExpect(jsonPath("$.xxx").value(expectValue))
 .andDo(document(doc_title,
 requestFields(
 fieldWithPath("xxx").description("xxx"),
 fieldWithPath("xxx").description("xxx")
 ), responseFields(
 fieldWithPath("xxx").description("xxx"),
 fieldWithPath("xxx").description("xxx")
 ) ));

• 改造后：

this.webTestClient.post().uri("/xx/xx/xx")
 .contentType(MediaType.APPLICATION_JSON_UTF8).accept(MediaType.APPLICATION_JSON)
 .body(Mono.just(requstObject), RequstObject.class)
 .exchange()
 .expectStatus().isOk()
 .expectBody()
 .jsonPath("$.xx").isEqualTo(expectValue)
 .consumeWith(WebTestClientRestDocumentation.document(doc_title,
 requestFields(
 fieldWithPath("xxx").description("xxx"),
 fieldWithPath("xxx").description("xxx")
 ), responseFields(
 fieldWithPath("xxx").description("xxx"),
 fieldWithPath("xxx").description("xxx")
 ) ));

现在就可以继续使用junit测试案例自动生成ascii的接口文档了。