使用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 依赖后，会有

<build><!--当项目没有规定目标时的默认值，项目没有报错，不用加 --><defaultGoal>compile</defaultGoal><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><!--手动添加snippets 属性节点，snippets的中文意思叫片段--><attributes><!--${project.build.directory} 是固定这么写的，指示项目文件夹的target目录,generated-snippets配置生成片段的存放路径--><snippets>${project.build.directory}\generated-snippets</snippets></attributes></configuration></execution></executions><dependencies><dependency><groupId>org.springframework.restdocs</groupId><artifactId>spring-restdocs-asciidoctor</artifactId><version>2.0.3.RELEASE</version></dependency></dependencies></plugin><!-- 这个插件配置主要是将generated-docs生成的在HTML接口文档复制到项目的静态文件夹中，以便将项目打包成jar包后，能够访问生成的接口文档--><plugin><artifactId>maven-resources-plugin</artifactId><version>2.7</version><executions><execution><id>copy-resources</id><phase>prepare-package</phase><goals><goal>copy-resources</goal></goals><configuration><outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory><resources><resource><directory>${project.build.directory}/generated-docs</directory></resource></resources></configuration></execution></executions></plugin><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>

编写测试代码

编写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<String, String> 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@Rulepublic JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");private MockMvc mockMvc;@Autowiredprivate WebApplicationContext context;@Beforepublic void setUp() {this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).apply(documentationConfiguration(this.restDocumentation)).build();}@Testpublic 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: aaaa@aliyun.com
:revnumber: v1.0
:revdate: 2019-07-13
:toc: left
:toc-title: hello模块 目录== 哈哈
个发几个好几个好几个== 哈哈 2
根据根据考核接口会尽快哈{snippets} 就是我们在pom.xml配置的<snippets></snippets>标签
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…