Testing——Spring REST Docs

Spring REST Docs

        依赖说明：通过结合使用 Ascidoctor 手写和使用 Spring MVC 测试生成的自动生成的片段来记录 RESTful 服务。

        Spring REST Docs 是一个为 Spring 项目生成 API 文档的框架，它通过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。

        Spring REST Docs 可以生成准确可读的RESTful Service文档（当然一般的API文档同样得心应手）。

Spring 官方文档都是用 Spring REST Docs 生成的，其简洁性和可读性也是大家都认可的，不过 Spring REST Docs 的优势远不止于此：

• 代码无污染：Spring REST Docs 基于单元测试生成文档片段（snippets），不会侵入到源码中，所以就不会使得源码变得越来越臃肿。
• 单元测试：因为文档的生成是依赖单元测试的，以此可以矫正一些不爱写单元测试的程序员小哥哥。
• 支持 markdown：修改一行配置代码即可支持生成 MarkDown 语法的文档片段（不过要生成html文档目前官方只支持adoc文档）。
• 文档自动更新：文档自动更新？文档自动更新！默认的，在构建的时候，会首先运行单元测试，此时便生成了文档片段，然后在打包时，通过添加 asciidoctor-maven-plugin 插件即可生成最终的文档，只要是规范的开发过程，文档都会随版本的每次发布而自动更新！
• 可读性高：Spring 官方文档就是个例子。
• ……

---

参考：

Spring REST Docs 介绍

Spring REST Docs 简易教程

使用Spring REST Docs 编写接口文档

Swagger2与Spring REST Docs

SpringBoot精藏（八）Spring restDocs创建API文档

用spring Restdocs创建API文档

---

POM

<!--Spring REST Docs-->
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
</dependency>

XXX