关于java:使用springrestdocswebtestclient为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 的接口文档了。