SpringBoot非官方教程 | 第十篇：用Spring Restdocs创建API文档

RdouTyping 发布于2019-08-16 10:44 / 1980人阅读

摘要：建一个单元测试类其中，注解开启了生成文件，并指定了存放位置。怎么用创建一个新文件用构建文档这个例子非常简单，通过单元测试和一些简单的配置就能够得到文档了。

准备工作

你需要15min
Jdk 1.8
maven 3.0+
idea

创建工程

引入依赖，其pom文件：


    
        org.springframework.boot
        spring-boot-starter-web
    

    
        org.springframework.boot
        spring-boot-starter-test
        test
    

    
        org.springframework.restdocs
        spring-restdocs-mockmvc
        test

通过@SpringBootApplication,开启springboot

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

在springboot通常创建一个controller：

@RestController
public class HomeController {

    @GetMapping("/")
    public Map greeting() {
        return Collections.singletonMap("message", "Hello World");
    }

}

启动工程，访问localhost:8080，浏览器显示：

{“message”:”Hello World”}

证明接口已经写好了，但是如何通过restdoc生存api文档呢

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-...，这里不多讲解。

需要使用asciidoctor-maven-plugin插件，在其pom文件加上：


    org.asciidoctor
    asciidoctor-maven-plugin
    
        
            generate-docs
            prepare-package
            
                process-asciidoc
            
            
                index.adoc
                html
                
                    ${project.build.directory}/snippets

这时只需要通过mvnw package命令就可以生成文档了。
在/target/generated-docs下有个index.html，打开这个html,显示如下，界面还算简洁：

结语

通过单元测试，生存adoc文件，再用adoc文件生存html，只需要简单的几步就可以生成一个api文档的html文件，这个html文件你可以通网站发布出去。整个过程很简单，对代码无任何影响。

源码下载：https://github.com/forezp/Spr...

参考资料

restdocs

http://docs.spring.io/spring-...

混合云私有云第十篇 webrtc api 官方文档 webrtc api官方文档 linux创建文档

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/70370.html

一起来学SpringBoot | 第十篇：使用Spring Cache集成Redis

摘要：特点具备相当的好的灵活性，不仅能够使用来定义缓存的和各种，还提供开箱即用的缓存临时存储方案，也支持和主流的专业缓存例如的集成。其中号代表这是一个表达式，此表达式可以遍历方法的参数对象，具体语法可以参考的相关文档手册。 SpringBoot 是为了简化 Spring 应用的创建、运行、调试、部署等一系列问题而诞生的产物，自动装配的特性让我们可以更好的关注业务本身而不是外部的XML配置，...

littleGrow 2019-08-16 12:35 评论0 收藏0
一起来学SpringBoot | 第十篇：使用Spring Cache集成Redis

摘要：特点具备相当的好的灵活性，不仅能够使用来定义缓存的和各种，还提供开箱即用的缓存临时存储方案，也支持和主流的专业缓存例如的集成。其中号代表这是一个表达式，此表达式可以遍历方法的参数对象，具体语法可以参考的相关文档手册。 SpringBoot 是为了简化 Spring 应用的创建、运行、调试、部署等一系列问题而诞生的产物，自动装配的特性让我们可以更好的关注业务本身而不是外部的XML配置，...

shadajin 2019-08-06 13:34 评论0 收藏0
Gradle环境下导出Swagger为PDF

摘要：没错，不支持，从导出的文档也可以看到，部分中文无法显示，目前我也尚未找到是否有配置可以实现这个功能。相对前面的方式，使用起来更加简单，也可以修改配置输出中文。更多精彩博文，欢迎访问我的个人博客说明我个人是一直使用Swagger作为接口文档的说明的。但是由于在一些情况下，接口文档说明需要以文件的形式交付出去，如果再重新写一份文档难免有些麻烦。于是在网上看到了Swagger2Mar...

OnlyMyRailgun 2019-08-16 18:23 评论0 收藏0
Spring Boot [如何优雅的编写文档]

摘要：导读在团队协作的时候许多时候需要用到接口文档，我们通常通过手工编写大量重复格式的文档，让我想起了程序员最讨厌的两件事没有文档，编写文档。对应的资料可自行谷歌。关于和官网是这样描述的。我们可以理解为为基于构建的自动生成文档。导读：在团队协作的时候许多时候需要用到接口文档，我们通常通过手工编写大量重复格式的文档，让我想起了程序员最讨厌的两件事：没有文档，编写文档。哈哈，如果使用过swa...

曹金海 2019-08-16 10:33 评论0 收藏0