使用Spring REST Docs 编写接口文档

Spring REST Docs 概述

Spring REST Docs 是基于 jdk1.8 和SpringFramework 5.0.2及以上版本的RESTful 服务文档，Spring REST Docs是通过将手写xxx.adoc文档与使用spring-mvc-test-framework测试框架编写的测试代码片段相结合的方式，来最终生成HTML接口文档，记录RESTful服务接口文档，是半自动的。

Spring REST Docs 与 Swagger 的区别

1.swagger是在线文档（传说也可以生成离线的），Spring REST Docs是离线文档
2.swagger是自动生成的,不可修改文档格式样式，Spring REST Docs 是半自动的，生成 的HTML文档样式不满意可以自定义
3.最主要的区别：swagger是对业务代码中有入侵性的，Spring REST docs是不需要修改业务代码的，没有入侵性

框架搭建

基于Spring boot ，去htttps://start.spring.io,搜索并添加Spring REST Docs 依赖

修改pom.xml

当你添加好maven 依赖后，会有

		
		compile
		
		
			
				org.asciidoctor
				asciidoctor-maven-plugin
				1.5.3
				
					
						generate-docs
						prepare-package
						
							process-asciidoc
						
						
							html
							book
							
								
									
									${project.build.directory}\generated-snippets
								
						
					
				
				
					
						org.springframework.restdocs
						spring-restdocs-asciidoctor
						2.0.3.RELEASE
					
				
			

			
			
				maven-resources-plugin
				2.7
				
					
						copy-resources
						prepare-package
						
							copy-resources
						
						
							
								${project.build.outputDirectory}/static/docs
							
							
								
									
										${project.build.directory}/generated-docs
									
								
							
						
					
				
			

			
				org.springframework.boot
				spring-boot-maven-plugin
			
			
		
	

编写测试代码

编写Controller代码

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;
import java.util.Map;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public Map hello(@RequestParam("page") String page, @RequestParam("per_page") String perPage){
        Map map = new HashMap<>();
        map.put("hello", "true");
        return map;
    }
 }   

使用MockMvc编写测试代码

import org.junit.Before;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.JUnitRestDocumentation;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
//静态导入
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;

@RunWith(SpringRunner.class)
@SpringBootTest
public class DemoApplicationTests {
    //如果没有写，默认的输出目录也是target/generated-snippets
    @Rule
    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
    private MockMvc mockMvc;
    @Autowired
    private WebApplicationContext context;

    @Before
    public void setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();
    }

    @Test
    public void contextLoads() throws Exception {
        this.mockMvc.perform(get("/hello?page=2&per_page=100").accept(MediaType.APPLICATION_JSON).header("Authorization", "Basic dXNlcjpzZWNyZXQ="))
                .andDo(print()).andExpect(status().isOk())ts
                .andDo(document("hello",
              //hello为文档的Id,在target/generated-snippets文件夹下会生成hello文件夹存放snippets片段
                        requestHeaders(
                                headerWithName("Authorization").description(
                                        "Basic auth credentials")),
                        requestParameters(
                                parameterWithName("page").description("The page to retrieve"),
                                parameterWithName("per_page").description("Entries per page")
                        )));
    }

编写index.adoc 代码片段

1.首先在src/main文件夹下创建一个名称为asciidoc的文件夹，名称固定，不可变。也可以选择用File API代码创建
2.在asciidoc文件夹下，创建一个名称为index.adoc的文件，该文件名可任意
3.每一个xxx.adoc，最终都会生成xxx.html 存放在/target/generated-doc文件夹中,同时也会存放在/target/classes/static/docs文件中，以便访问
4.要熟悉asciidoctor语法才能较好的编写adoc代码片段，
官网手册链接地址：https://asciidoctor.org/docs/user-manual
其他博客asciidoctor基础语法：https://blog.csdn.net/jioujiou520/article/details/90613175
5.编写接口文档目录
使用 :toc: left 命令使目录往左边放，其中left前面有一个空格
使用**:toc-title:** xxx模块的总目录名
使用= 空格 零级目录名
使用== 空格 一级目录名
使用=== 空格 一级目录名
使用//// 包裹起来表示注释 ////

= 接口文档
:author: LJH
:email: [email protected]
:revnumber: v1.0
:revdate: 2019-07-13
:toc: left
:toc-title: hello模块 目录


== 哈哈
个发几个好几个好几个

== 哈哈 2
根据根据考核接口会尽快哈

////
{snippets} 就是我们在pom.xml配置的标签
hello 就是我们在测试代码里写的文档Id叫hello
include::{snippets}\hello\curl-request.adoc[]
include::{snippets}\hello\httpie-request.adoc[]
include::{snippets}\hello\response-body.adoc[]
include::{snippets}\hello\request-body.adoc[]
////
.http-request
include::{snippets}\hello\http-request.adoc[]
.request-headers 请求头说明
include::{snippets}\hello\request-headers.adoc[]
.request-parameters 请求参数说明
include::{snippets}\hello\request-parameters.adoc[]
include::{snippets}\hello\http-response.adoc[]

== 哈哈 3
 和的范德萨范德萨返回多行

昨晚边试错边学习硬是搞到凌晨3点多…

生成的代码片段存放的目录

target目录的结构

index.html存放目录

index.html接口页面展示

引用曹雪芹的诗一首

满纸荒唐言

一把辛酸泪

都言作者痴

谁解其中味

持续努力中…努力coding…