1 创建SpringBoot Demo项目
- 创建Maven项目
- 修改pom文件，改为springboot项目，增加spring-restdocs-mockmvc依赖
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.0</version>
</parent>
<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>
</dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
</dependency>
</dependencies>
2 项目代码
package com.doc.controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.doc.BaseRespVO;
import com.doc.TestReqVO;
import com.doc.TestRespVO;
/**
* 测试类
*
* @author young
* @since 2021-04-29
*
*/
@RestController
@RequestMapping("/test")
public class TestController {
/**
* 测试方法1
*
* @param test
* @return
*/
@RequestMapping(value = "req-test", method = RequestMethod.GET)
public BaseRespVO<TestRespVO> reqTest(String test) {
BaseRespVO<TestRespVO> respVO = new BaseRespVO<>();
return respVO;
}
/**
* 测试方法2
*
* @param reqVO
* @return
*/
@RequestMapping(value = "resp-test", method = RequestMethod.POST)
public BaseRespVO<Void> respTest(@RequestBody TestReqVO reqVO) {
BaseRespVO<Void> respVO = new BaseRespVO<>();
return respVO;
}
}
package com.doc;
public class TestReqVO {
/**
* 国家
*/
private String country;
/**
* 省
*/
private String province;
/**
* 市
*/
private String city;
/**
* 姓名
*/
private String name;
/**
* 年龄
*
*/
private int age;
public String getCountry() {
return country;
}
public void setCountry(String country) {
this.country = country;
}
public String getProvince() {
return province;
}
public void setProvince(String province) {
this.province = province;
}
public String getCity() {
return city;
}
public void setCity(String city) {
this.city = city;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
}
package com.doc;
public class TestRespVO {
/**
* 唯一id
*/
private int id;
/**
* 随机码uuid
*
*/
private String uuid;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getUuid() {
return uuid;
}
public void setUuid(String uuid) {
this.uuid = uuid;
}
}
package com.doc;
/**
* 返回数据Base对象
*/
public class BaseRespVO<T> {
/**
* 返回码
*
*/
private int code = 0;
/**
* 返回码描述信息
*
*/
private String desc;
/**
* 返回数据
*
*/
protected T data;
public T getData() {
return data;
}
public void setData(T data) {
this.data = data;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getDesc() {
return desc;
}
public void setDesc(String desc) {
this.desc = desc;
}
@Override
public String toString() {
return super.toString();
}
}
3 Junit测试
package com.doc.controller;
// 静态导入MockMvcRequestBuilders.* MockMvcResultHandlers.* MockMvcRestDocumentation.*
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.*;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
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.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import com.doc.TestReqVO;
import com.fasterxml.jackson.databind.ObjectMapper;
@WebMvcTest(TestController.class)
@AutoConfigureRestDocs
class TestControllerTest {
@Autowired
private MockMvc mvc;
@Test
void reqTest() throws Exception {
mvc.perform(get("/test/req-test").param("test", "123456")).andDo(print())
.andDo(document("E:\\data\\doc\\snippets\\reqTest"));
}
@Test
void respTest() throws Exception {
TestReqVO reqVO = new TestReqVO();
reqVO.setCountry("China");
reqVO.setProvince("GuangDong");
reqVO.setCity("ShenZhen");
reqVO.setName("TestName");
reqVO.setAge(18);
mvc.perform(post("/test/resp-test").content(toJsonString(reqVO)).contentType(MediaType.APPLICATION_JSON))
.andDo(print()).andDo(document("E:\\data\\doc\\snippets\\respTest"));
}
public static String toJsonString(Object jsonObj) {
try {
ObjectMapper mapper = new ObjectMapper();
String jsonContent = mapper.writeValueAsString(jsonObj);
return jsonContent;
} catch (Exception e) {
throw new RuntimeException(e);
}
}
}
执行Junit测试，在E:\data\doc\snippets\reqTest和E:\data\doc\snippets\respTest生成文件：
curl-request.adoc
httpie-request.adoc
http-request.adoc
http-response.adoc
request-body.adoc
response-body.adoc
4 汇总文档
- 创建src\main\asciidoc\index.adoc文件，包含snippets中的adoc
This is an example output for a service running at http://localhost:8080:
# TestController.reqTest
.curl
include::{snippets}\reqTest\curl-request.adoc[]
.request
include::{snippets}\reqTest\http-request.adoc[]
.response
include::{snippets}\reqTest\http-response.adoc[]
# TestController.respTest
.curl
include::{snippets}\respTest\curl-request.adoc[]
.request
include::{snippets}\respTest\http-request.adoc[]
.response
include::{snippets}\respTest\http-response.adoc[]
- pom文件配置插件：
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>html</backend>
<attributes>
<snippets>E:\data\doc\snippets</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
- 执行
mvn package生成文档target\generated-docs\index.html
5 结果预览
doc.png
