Spring REST Docs 简易教程

Spring REST Docs 简易教程

By 鱼泡泡技术团队

---

• 原文出自：
  1、http://blog.youkuaiyun.com/anxpp/article/details/73330832
  2、http://blog.anxpp.com/index.php/archives/1071

• 本文相当于官方文档的部分翻译版，Demo中还做了一些扩展，以使整个文档生成工作更加顺利，完整文档请参考Spring REST Docs 官方文档。

• *网上随便找了找，中文资料几乎没有，只能硬着头皮带着跛脚的英语看起了官方文档，并分享如下…
  文章写得很渣，直接下载文末的 Demo 通常会上手更快!*

---

目录

---

简介

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 全家桶的每一个组件，都堪称极品。

---

整合 Spring REST Docs

Spring REST Docs 同时支持Maven和Gradle，不过个人偏爱Maven，一下仅介绍Maven下的整合，Gradle请查看官方文档。
生成文档片段的单元测试同时支持 Spring MVC Test 和 REST Assured 2/3，对比了一下，Spring MVC Test的代码更加简洁，
所以本文也使用 Spring MVC Test 来做单元测试，如果有兴趣使用 Assured 的，依然还是参考官方文档吧。

Build configuration

在pom.xml文件中添加依赖和构建插件：

• spring-restdocs-mockmvc用于编写单元测试
• 添加Asciidoctor插件
• prepare-package 参数允许文档被添加到程序包中

<dependency> 
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>1.2.1.RELEASE</version>
    <scope>test</scope>
</dependency>

<build>
    <plugins>
        <plugin> 
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <phase>prepare-package</phase> 
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html</backend>
                        <doctype>book</doctype>
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency> 
                    <groupId>org.springframework.restdocs</groupId>
                    <artifactId>spring-restdocs-asciidoctor</artifactId>
                    <version>1.2.1.RELEASE</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

这样，在单元测试时，就能在对应的输出目录里生成对应的文档片段（adoc文档片段或者MarkDown文档片段）。

将文档打包到jar中

如果希望生成的jar中直接包含文档，可以在 maven-resourc