使用Spring REST Docs 编写接口文档

最新推荐文章于 2025-04-08 14:02:40 发布
最新推荐文章于 2025-04-08 14:02:40 发布
阅读量1.2w 收藏 10
点赞数 4
分类专栏： 编写接口文档 java 文章标签： 编写接口文档
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/ljh_learn_from_base/article/details/95866258
版权

目录

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
    @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.youkuaiyun.com/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目录的结构

target目录的结构

index.html存放目录

index.html存放目录
index.html存放目录

index.html接口页面展示

index.html接口页面展示
index.html接口页面展示

引用曹雪芹的诗一首

满纸荒唐言

一把辛酸泪

都言作者痴

谁解其中味

持续努力中…努力coding…

Spring Rest Docs使用
Huangjiazhen711的博客
10-10 1209
今天给大家分享一个能通过代码自动生成文档技术，Spring Rest Doc过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。下面通过一个简单的例子演示下如何快速上手的。在Spring Boot项目中添加maven 依赖在controller添加接口编写测试用例，并且输出文档。在target目录可以看到生成文档。
Spring REST Docs 简易教程
anxpp的博客
06-17 7935
Spring REST Docs 简易教程 本文相当于官方文档的部分翻译版，完整文档请参考Spring REST Docs 官方文档 ，本文涉及内容： 简介 Spring REST Docs 整合 为API编写文档 配置 Asciidoctor 使用简介 Demo 源码...
spring restdocs
lovelyesz的博客
03-18 604
spring restdocs 最近不知道怎么了，我和一个同事疯狂了迷恋上了spring的一些工具型框架，不为人所知但是功能也很强大，今天就记录一下对springrestdocs的研究记录。 rest-docs翻译一下restful风格的文档，这么说跟swagger很像喽？后来我才发现太小看swagger了，作为一个功能性框架springrestdocs的原理没什么亮点，它的功能...
SpringDoc【使用详解】
最新发布
qq_27480007的博客
04-08 1904
SpringDoc【使用详解】
Spring REST Docs 介绍
Talk is cheap，show me the code.
02-26 7930
Spring REST Docs 是一个为 Spring 项目生成 API 文档的框架，它通过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。 本文会以一个最简单的示例介绍如何在一个 Spring Boot 应用中使用 Spring REST Docs，并在最后与目前最常见的 SpringFox 进行一些对比，分别介绍其特点和优劣。   基础准备 首先需要一个 Spri...
Spring REST Docs 教程
gitblog_00318的博客
08-10 536
Spring REST Docs 教程 spring-restdocsTest-driven documentation for RESTful services项目地址:https://gitcode.com/gh_mirrors/sp/spring-restdocs 1. 项目介绍 Spring REST Docs 是一个用于生成 RESTful APIs 文档的框架，它专注于通过自动化的方...
推荐使用：Spring REST Docs - 让你的RESTful服务文档更上一层楼！
gitblog_00318的博客
08-10 478
推荐使用：Spring REST Docs - 让你的RESTful服务文档更上一层楼！ 项目地址:https://gitcode.com/gh_mirrors/sp/spring-restdocs 项目简介 Spring REST Docs 是一个致力于简化RESTful服务文档编写的开源项目。它将手工编写的Asciidoctor文档与Spring MVC Test框架自动生成的示例相结合，为用...
详解如何用spring Restdocs创建API文档
08-30
Spring Restdocs 是一个用于生成 API 文档的框架，它由 Spring 官方推荐，主要用于简化 API 文档的创建过程。这个框架与 Spring Boot 结合使用，可以方便地通过单元测试来自动化生成 API 文档，避免手动编写繁琐的...
Spring REST Docs 扩展项目，简化文档编写.zip
11-15
压缩包中包含的文件“spring-auto-restdocs”可能是一个自动生成的Spring REST Docs配置或工具文件，这将使得文档的自动化和标准化更为简便。通过这个名字，我们可以推测这是一个简化了文档自动生成过程的工具，它...
spring-auto-restdocs：Spring Auto REST文档是Spring REST文档的扩展
01-29
您仍然可以获得与Spring REST Docs本身相同的文档。 主要好处是减少了编写并使文档更接近代码，从而提高了文档的可维护性。 在Spring REST Docs中，您必须在测试中添加带有DSL的JSON文档。 我们将此文档移至代表您...
Testing——Spring REST Docs
十年梦归尘的专栏
12-09 747
Spring REST Docs
RESTful服务文档SpringRESTDocs.zip
07-18
Spring REST Docs 帮助你管理 RESTful 服务文档，使用 Asciidoctor 来编写文档，使用 Spring MVC Test. 自动生成片段。 标签：Spring
spring-restdocs:测试驱动的RESTful服务文档
05-13
Spring REST文件 概述 该项目的主要目标是通过结合使用与使用框架生成的自动生成的示例，从而轻松记录RESTful服务。 结果旨在成为一个易于阅读的用户指南，例如类似于，而不是由类的工具生成的全自动，密集的API文档。 有关更广泛的介绍，请参见Documenting RESTful APIs演示。 和均可用。 了解更多 要了解有关Spring REST Docs的更多信息，请查阅。 从源头建造 您将需要Java 8或更高版本来构建Spring REST Docs。 它是使用构建的： ./gradlew build 贡献 该项目的贡献者同意遵守其。 您可以为Spring REST Docs做一些贡献： 打开拉取请求。 有关详细信息，请参见贡献者指南。 使用spring-restdocs标签在Stack Overflow上提问和回答问题。 在Gitter上与其他用户聊天。
Spring REST Docs API（Spring REST Docs 开发文档）.CHM
08-31
Spring REST Docs。 官网 Spring REST Docs API。 Spring REST Docs 开发文档。
Spring REST Docs 构建java项目文档
强哥叨逼叨
09-22 790
最近因为项目中需要编写接口文档，原来用的swagger结合现有项目问题比较多，且没有直观的目录（不知道swagger是否有左边栏目录这样的形式，没去细查），配合前端和测试使用时，他们抱怨比较多，所以摒弃了swagger之后，找到了spring rest docs， 结合官方文档和网上查到的资料，成功生成了接口文档。样例如下：
使用spring-restdocs 自动生成接口文档
热门推荐
神夏的博客
08-14 1万+
前言 Spring REST Docs helps you to document RESTful services. It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test. This approach fr
Spring系列学习之Spring REST Docs
纸上得来终觉浅，绝知此事要躬行
12-22 1718
英文原文：https://spring.io/projects/spring-restdocs 目录 概述 Spring Boot配置 快速开始 学习 文档 示例 概述 Spring REST Docs可帮助您记录RESTful服务。 它结合了使用Asciidoctor编写的手写文档和使用Spring MVC Test生成的自动生成的片段。 这种方法使您免受Swagger等工具生...
Spring REST Docs 2.0.4
BLOG域名:programb.blog.youkuaiyun.com
05-12 179
Overview Learn Samples Spring REST Docs helps you to document RESTful services. It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test. This approach frees you from the limitations of the
新增Spring REST Docs API规范支持功能详解
总结来说，restdocs-api-spec扩展是Spring REST Docs的一个重要补充，它增加了对API规范格式的支持，尤其是json和yaml，从而让文档具有更好的可读性和可用性。通过这种方式，开发团队能够使用一个统一的框架来生成和...
评论 2
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值