SpringCloud SpringBoot mybatis 分布式微服务(二十五)创建API文档
2018-03-01 10:04
786 查看
Restdoc,通过单元测试生成api文档
restdocs是通过单元测试生存snippets文件,然后snippets根据插件生成htm文档的。建一个单元测试类:@RunWith(SpringRunner.class)@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"));
}
}
其中,@ AutoConfigureRestDocs注解开启了生成snippets文件,并指定了存放位置。启动单元测试,测试通过,你会发现在target文件下生成了一个snippets文件夹,其目录结构如下:└── target
└── snippets
└── home
└── httpie-request.adoc
└── curl-request.adoc
└── http-request.adoc
└── http-response.adoc
默认情况下,snippets是Asciidoctor格式的文件,包括request和reponse,另外其他两种httpie和curl两种流行的命令行的http请求模式。到目前为止,只生成了Snippets文件,需要用Snippets文件生成文档。
怎么用Snippets
创建一个新文件src/main/asciidoc/index.adoc := 用 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[]
这个例子非常简单,通过单元测试和一些简单的配置就能够得到api文档了。
adoc的书写格式,参考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/,这里不多讲解。需要使用asciidoctor-maven-plugin插件,在其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>${project.build.directory}/snippets</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
这时只需要通过mvnw package命令就可以生成文档了。
在/target/generated-docs下有个index.html,打开这个html,显示如下,界面还算简洁:
源码来源
相关文章推荐
- Spring Cloud Spring Boot mybatis分布式微服务云架构(二十五)整合MyBatis
- Spring Cloud Spring Boot mybatis分布式微服务云架构(四)属性配置文件详解(2)
- Spring Cloud Spring Boot mybatis分布式微服务云架构(三)属性配置文件详解(1)
- Spring Cloud Spring Boot mybatis分布式微服务云架构(六)RESTful API单元测试
- Spring Cloud Spring Boot mybatis分布式微服务云架构(七)开发Web应用(1)
- SpringCloud SpringBoot mybatis 分布式微服务(四)Spring Boot开发Web应用
- Spring Cloud Spring Boot mybatis分布式微服务云架构(十六)使用JdbcTemplate操作数据库
- SpringCloud SpringBoot mybatis 分布式微服务(二十六)集成swagger2构建Restful API
- Spring Cloud Spring Boot mybatis分布式微服务云架构(五)构建RESTful API
- Spring Cloud Spring Boot mybatis分布式微服务云架构-开发Web应用
- Spring Cloud Spring Boot mybatis分布式微服务云架构(十二)返回JSON格式
- SpringCloud SpringBoot mybatis 分布式微服务(二十四)整合Redis
- Spring Cloud Spring Boot mybatis分布式微服务云架构(四十六)使用RabbitMQ(1)
- Spring Cloud Spring Boot mybatis分布式微服务云架构(八)开发Web应用(2)
- SpringCloud SpringBoot mybatis 分布式微服务(二十九)Restdoc生成api文档
- Spring Cloud Spring Boot mybatis分布式微服务云架构-开发Web应用2
- Spring Cloud Spring Boot mybatis 企业分布式微服务云(八)服务容错保护(Hystrix依赖隔离)【Dalston版】
- Spring Cloud Spring Boot mybatis分布式微服务云架构(三十九)对log4j进行多环境不同日志级别的控制
- Spring Cloud Spring Boot mybatis分布式微服务云架构(十一)Web应用的统一异常处理
- SpringCloud SpringBoot mybatis 分布式微服务(十二)Spring Boot中使用Redis数据库