Spring REST Docs 构建java项目文档

最新推荐文章于 2024-08-10 07:16:17 发布
最新推荐文章于 2024-08-10 07:16:17 发布
阅读量746 收藏 2
点赞数 1
分类专栏： java 文章标签： java 文档 spring
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/seanxwq/article/details/78064599
版权

最近因为项目中需要编写接口文档，原来用的swagger结合现有项目问题比较多，且没有直观的目录（不知道swagger是否有左边栏目录这样的形式，没去细查），配合前端和测试使用时，他们抱怨比较多，所以摒弃了swagger之后，找到了spring rest docs， 结合官方文档和网上查到的资料，成功生成了接口文档。样例如下：

接口文档样例

spring rest docs的使用其实就是在你现有的spring mvc或spring boot的项目上，配置生成文档的依赖包，然后编写接口单元测试，编写adoc配置文件，最后打包自动生成html接口文档的过程。根据这个步骤一步步操作：

1、配置依赖：

<dependency>
			<groupId>org.springframework.restdocs</groupId>
			<artifactId>spring-restdocs-mockmvc</artifactId>
			<scope>test</scope>
		</dependency>
<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
			<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>
						<version>1.2.1.RELEASE</version>
					</dependency>
				</dependencies>
			</plugin>
			<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>
		</plugins>
	</build>
2、编写接口测试

我们通过mock进行接口测试编写，测试类属性配置及单测前的before方法：

	@Rule
	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");//生成的adoc文件导出目录
	private MockMvc mockMvc;
	@Autowired
	private WebApplicationContext context;

	@Before
	public void setUp() {
		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
				.apply(documentationConfiguration(this.restDocumentation))
//				.alwaysDo(document("{method-name}/{step}/"))
				.build();
	}
单测例子（与普通的mock测试多了红色标注的部分，语法什么的我就不在这里讲解了，要想写出来，肯定要看官方文档： 点击打开链接，如果不想看英文，看这个博客也可以： 点击打开链接，不过，还是强烈推荐看官方文档）： 

	@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())
				.andDo(document("hello 接口",//这个identity不同的单测需要不同，否则其他的测试会覆盖现有的，最后文档里只生成一个接口说明
						requestHeaders(
								headerWithName("Authorization").description(
										"Basic auth credentials")),
						requestParameters(
						parameterWithName("page").description("The page to retrieve"),
						parameterWithName("per_page").description("Entries per page")
				)));
	}
3、编写adoc配置文件

在maven项目标准结构下，src/main下新建asciidoc目录，并建一个.adoc为结尾的文件（到时候打包时，会根据asciidoc目录下的所有.adoc文件生成过个对应文件名的html文档）。例子如下：

== hello 接口
.http-request
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\http-request.adoc[]
.request-headers 请求头说明
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\request-headers.adoc[]
.request-parameters 请求参数说明
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\request-parameters.adoc[]
.http-response
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\http-response.adoc[]

== hello2 接口
.http-request
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello2 接口\http-request.adoc[]
.http-response
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello2 接口\http-response.adoc[]
4、ok，最后用maven打包项目，跑完之后，就可以在target/generated-docs下看到你的文件了，直接双击打开，就能看到生成的文档。

以上是根据官网文档，就可以导出一个接口文档。但是，并没有左边栏的目录，而且写一个单测就要在.adoc文件里添加include关键字导入新生成的接口内容很麻烦，怎么办呢？

首先，左边栏目录或右边栏目录，或直接在文档最开头添加目录我们只需要在.adoc文件开头添加如下内容：

= 接口文档
v1.0, 2017-09-22
:toc: left
它会自动根据你文件下发的接口配置来定义目录，前面第3点列出的那个配置红色部分就是接口的引用配置。是不是很简单，配置完之后，就能生成和我文档最开头那张图片的样子了。

然后解决每写一个接口测试就要在.adoc文件里添加include的问题：

我们编写.adoc文件生成功能，方法如下（参考了：点击打开链接）：

@Test
	public void adocBuild() throws IOException {
		String appDir = System.getProperty("user.dir");
		String adocPath = appDir + "\\src\\main\\asciidoc\\hello.adoc";
		StringBuilder content = new StringBuilder();
		content.append("include::" + appDir + "\\src\\main\\asciidoc\\preview.adoc[]").append(System.getProperty("line.separator")).append(System.getProperty("line.separator"));
		File apidirs = new File(appDir + "\\target\\generated-snippets");
		for (File apidir : apidirs.listFiles()) {
			String apiName = apidir.getName();
			content.append("== " + apiName + System.getProperty("line.separator"));
			fileAppend(content, apidir + "\\http-request.adoc", ".http-request");
			fileAppend(content, apidir + "\\request-headers.adoc", ".request-headers 请求头说明");
			fileAppend(content, apidir + "\\request-parameters.adoc", ".request-parameters 请求参数说明");
			fileAppend(content, apidir + "\\request-body.adoc", ".request-body 请求体说明");
			fileAppend(content, apidir + "\\http-response.adoc", ".http-response");
			fileAppend(content, apidir + "\\response-fields.adoc", ".response-fields 返回值说明");
			content.append(System.getProperty("line.separator"));
		}
//		System.out.println(adocPath);
//		System.out.println(content);
		File file = new File(adocPath);
		writeStringToFile(file, content.toString(), "UTF-8");
	}

	private void writeStringToFile(File file, String content, String character) throws IOException {
		if (!file.exists()) {
			file.createNewFile();
		}
		FileOutputStream fos = new FileOutputStream(file);
		OutputStreamWriter osw = new OutputStreamWriter(fos, character);
		osw.write(content);
		osw.flush();
	}

	private void fileAppend(StringBuilder content, String include, String title) {
		File file = new File(include);
		if (file.exists()) {
			content.append(title).append(System.getProperty("line.separator"));
			content.append("include::").append(include).append("[]").append(System.getProperty("line.separator"));
		}
	}
很简单，也就是编写方法，创建文件，写入内容。

对啦，告诉你们我是怎么知道加那个目录的，当然是看asciidoctor的语法文档啦,在这里：点击打开链接

嗯，项目源码在此：拿去参考吧，直接就能运行：点击打开链接

强哥叨逼叨
关注
  • 1
    点赞
  • 踩
  • 2
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
RESTful服务文档SpringRESTDocs.zip
07-18
Spring REST Docs 帮助你管理 RESTful 服务文档，使用 Asciidoctor 来编写文档，使用 Spring MVC Test. 自动生成片段。 标签：Spring
spring restdocs
lovelyesz的博客
03-18 556
spring restdocs 最近不知道怎么了，我和一个同事疯狂了迷恋上了spring的一些工具型框架，不为人所知但是功能也很强大，今天就记录一下对springrestdocs的研究记录。 rest-docs翻译一下restful风格的文档，这么说跟swagger很像喽？后来我才发现太小看swagger了，作为一个功能性框架springrestdocs的原理没什么亮点，它的功能...
API开发秘籍：揭秘Swagger与Spring REST Docs的文档自动化神技
Geek_H
06-02 998
API文档是开发者与用户之间的桥梁，但手动编写文档既耗时又容易出错。将为你揭开Swagger和Spring REST Docs的神秘面纱，展示如何通过自动化工具将API文档提升到一个全新的水平。通过实际案例，我们将一步步教你如何集成这些工具，利用注解和测试生成既美观又实用的文档。无论你是API新手还是资深开发者，本文都将为你的API开发之旅增添一份强大的助力。
Spring REST Docs 介绍
Talk is cheap，show me the code.
02-26 7715
Spring REST Docs 是一个为 Spring 项目生成 API 文档的框架，它通过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。 本文会以一个最简单的示例介绍如何在一个 Spring Boot 应用中使用 Spring REST Docs，并在最后与目前最常见的 SpringFox 进行一些对比，分别介绍其特点和优劣。   基础准备 首先需要一个 Spri...
Spring Rest Docs使用
Huangjiazhen711的博客
10-10 1094
今天给大家分享一个能通过代码自动生成文档技术，Spring Rest Doc过在单元测试中额外添加 API 信息描述，从而自动生成对应的文档片段。下面通过一个简单的例子演示下如何快速上手的。在Spring Boot项目中添加maven 依赖在controller添加接口编写测试用例，并且输出文档。在target目录可以看到生成文档。
Testing——Spring REST Docs
十年梦归尘的专栏
12-09 694
Spring REST Docs
spring-restdocs:测试驱动的RESTful服务文档
05-13
Spring REST文件 概述 该项目的主要目标是通过结合使用与使用框架生成的自动生成的示例，从而轻松记录RESTful服务。... 使用spring-restdocs标签在Stack Overflow上提问和回答问题。 在Gitter上与其他用户聊天。
sfg-restdocs-example：Spring REST文档示例
02-20
【标题】"sfg-restdocs-example：Spring REST文档示例"是一个开源项目，它为学习和理解如何在Spring框架中使用Spring REST Docs提供了一个实际的示例。这个项目是针对那些想要提升其API文档质量的Java开发人员设计的...
spring-restdocs-example
05-01
《Spring Restdocs实战示例详解》 在Java开发领域，Spring...通过实践这个例子，开发者不仅可以掌握Spring Restdocs的基本用法，还能了解到如何在实际项目中构建、管理和维护API文档，提高工作效率，提升API的易用性。
springone2gx-2015-spring-restdocs-demo:SpringOne2GX 2015 Spring REST Docs演示的代码
05-10
5. **代码结构**: 文件名称列表"springone2gx-2015-spring-restdocs-demo-master"暗示了项目的根目录，其中可能包含源代码、测试代码、配置文件以及构建脚本。开发者可以查看这些文件来学习如何在自己的项目中集成...
apply_rest_docs:REST文档
03-17
本篇文章将深入探讨`apply_rest_docs`这个项目，它是与Java相关的REST文档生成工具，帮助开发者方便地创建和管理RESTful API的文档。 `apply_rest_docs`项目的核心目标是自动化REST API的文档生成过程，减少手动...
Spring REST Docs API（Spring REST Docs 开发文档）.CHM
08-31
Spring REST Docs。 官网 Spring REST Docs API。 Spring REST Docs 开发文档。
Spring REST Docs 2.0.4
BLOG域名:programb.blog.csdn.net
05-12 152
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-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 REST Docs 2.0.4.RELEASE
BLOG域名:programb.blog.csdn.net
05-14 259
Releases Andy Wilkinson September 30, 2019 On behalf of the community and everyone who has contributed, it’s my pleasure to announce that Spring REST Docs 2.0.4.RELEASE is available from Maven Central, JCenter, and our release repository. Thank you to ever
使用Spring REST Docs 编写接口文档
ljh_learn_from_base的博客
07-14 1万+
目录Spring REST Docs 概述Spring REST Docs 与 Swagger 的区别框架搭建修改pom.xml编写测试代码编写Controller代码使用MockMvc编写测试代码编写index.adoc 代码片段昨晚边试错边学习硬是搞到凌晨3点多.......生成的代码片段存放的目录target目录的结构index.html存放目录index.html接口页面展示引用曹雪芹的诗...
Spring REST Docs 简易教程
anxpp的博客
06-17 7721
Spring REST Docs 简易教程 本文相当于官方文档的部分翻译版，完整文档请参考Spring REST Docs 官方文档 ，本文涉及内容： 简介 Spring REST Docs 整合 为API编写文档 配置 Asciidoctor 使用简介 Demo 源码...
Spring系列学习之Spring REST Docs
纸上得来终觉浅，绝知此事要躬行
12-22 1676
英文原文：https://spring.io/projects/spring-restdocs 目录 概述 Spring Boot配置 快速开始 学习 文档 示例 概述 Spring REST Docs可帮助您记录RESTful服务。 它结合了使用Asciidoctor编写的手写文档和使用Spring MVC Test生成的自动生成的片段。 这种方法使您免受Swagger等工具生...
Spring REST Docs 教程
最新发布
gitblog_00318的博客
08-10 356
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
09-11
Spring REST Docs是一个基于Spring Boot2和JUnit5的工具，用于生成RESTful API的文档。它的默认文档主页可以放在`src/main/asciidoc/index.adoc`中。通过使用Spring REST Docs，你可以轻松地为你的API生成描述文档。...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值