SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
来源:互联网 发布:淘宝天猫的运营模式 编辑:程序博客网 时间:2024/05/21 07:00
转载请标明出处:
http://blog.csdn.net/forezp/article/details/71023510
本文出自方志朋的博客
这篇文章将带你了解如何用spring官方推荐的restdoc去生成api文档。本文创建一个简单的springboot工程,将http接口通过Api文档暴露出来。只需要通过 JUnit单元测试和Spring的MockMVC就可以生成文档。
准备工作
- 你需要15min
- Jdk 1.8
- maven 3.0+
- idea
创建工程
引入依赖,其pom文件:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
通过@SpringBootApplication,开启springboot
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
在springboot通常创建一个controller:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
启动工程,访问localhost:8080,浏览器显示:
{“message”:”Hello World”}
证明接口已经写好了,但是如何通过restdoc生存api文档呢
Restdoc,通过单元测试生成api文档
restdocs是通过单元测试生存snippets文件,然后snippets根据插件生成htm文档的。
建一个单元测试类:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
其中,@ AutoConfigureRestDocs注解开启了生成snippets文件,并指定了存放位置。
启动单元测试,测试通过,你会发现在target文件下生成了一个snippets文件夹,其目录结构如下:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
默认情况下,snippets是Asciidoctor格式的文件,包括request和reponse,另外其他两种httpie和curl两种流行的命令行的http请求模式。
到目前为止,只生成了Snippets文件,需要用Snippets文件生成文档。
怎么用Snippets
创建一个新文件src/main/asciidoc/index.adoc :
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
adoc的书写格式,参考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/,这里不多讲解。
需要使用asciidoctor-maven-plugin插件,在其pom文件加上:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
这时只需要通过mvnw package命令就可以生成文档了。
在/target/generated-docs下有个index.html,打开这个html,显示如下,界面还算简洁:
结语
通过单元测试,生存adoc文件,再用adoc文件生存html,只需要简单的几步就可以生成一个api文档的html文件,这个html文件你可以通网站发布出去。整个过程很简单,对代码无任何影响。
源码下载:https://github.com/forezp/SpringBootLearning
参考资料
restdocs
http://docs.spring.io/spring-restdocs/docs/current/reference/html5/
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- SpringBoot非官方教程 | 第十三篇:springboot集成spring cache
- SpringBoot非官方教程 | 第十三篇:springboot集成spring cache
- SpringBoot非官方教程 | 第十三篇:springboot集成spring cache
- SpringBoot非官方教程 | 第十三篇:springboot集成spring cache
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
- spring-restdocs利用测试用例生成API文档,AsciidocFX工具整合
- SpringBoot非官方教程 | 第二篇:Spring Boot配置文件详解
- SpringBoot非官方教程 | 第二篇:Spring Boot配置文件详解
- SpringBoot非官方教程 | 第二篇:Spring Boot配置文件详解
- SpringBoot非官方教程 | 第二篇:Spring Boot配置文件详解
- c语言返回局部变量
- SpringBoot非官方教程 | 第十五篇:Springboot整合RabbitMQ
- Linux作为服务端,Windows作为客户端socket通信
- Java动态代理之cglib
- Redis用bitset(bitmap)来统计日活跃量
- SpringBoot非官方教程 | 第十篇: 用spring Restdocs创建API文档
- leetcode 506. Relative Ranks
- UVA1579,俄罗斯套娃
- VMware Workstation虚拟机Ubuntu中实现与主机共享(复制和粘贴)
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
- c++文件保存与读取
- [模板]线性筛素数
- 数据分析(入门篇)-第一章-数据分析那些事儿
- Thinkphp5学习(26)调试和日志