Spring REST Docs 简易教程

最新推荐文章于 2024-08-10 07:55:26 发布

anxpp

最新推荐文章于 2024-08-10 07:55:26 发布

阅读量7.7k

点赞数 5

分类专栏： Spring全家桶文章标签： spring REST-DOC API文档文档

本文链接：https://blog.csdn.net/anxpp/article/details/73330832

版权

Spring REST Docs提供了一种优雅的方式，基于单元测试生成准确、可读的RESTful服务文档。它不污染源码，依赖于单元测试，支持Markdown格式，且能自动更新。本文介绍了整合Spring REST Docs的步骤，包括配置、文档片段生成、API文档编写等，通过实例代码展示如何使用MockMvc进行测试并生成文档。此外，还提到了Asciidoctor的使用，以及如何将文档打包到jar中。

摘要由CSDN通过智能技术生成

Spring REST Docs 简易教程

By 鱼泡泡技术团队

原文出自：
1、http://blog.csdn.net/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 全家桶的每一个组件，都堪称极品。

整合 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>
                    <