使用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引用，改为:

 org.springframework.boot
 spring-boot-starter-test
 test


 io.projectreactor
 reactor-test
 test


 org.springframework.restdocs
 spring-restdocs-webtestclient
 2.0.5.RELEASE

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

 org.apache.maven.plugins
 maven-surefire-plugin
 
 
 **/*Documentation.java
 
 


 org.asciidoctor
 asciidoctor-maven-plugin
 1.5.3
 
 
 generate-docs
 prepare-package
 
 process-asciidoc
 
 
 html
 book
 
 
 
 
 
 org.springframework.restdocs
 spring-restdocs-asciidoctor
 ${spring-restdocs.version}
 
 


 org.apache.maven.plugins
 maven-resources-plugin
 
 
 copy-resources
 prepare-package
 
 copy-resources
 
 
 ${project.build.outputDirectory}/static/docs
 
 
 ${project.build.directory}/generated-docs
 
 
 
 
 

准备一个测试用父类

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

@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的接口文档了。