SpringBoot 教程 & 笔记 |Demo07- 整合 Swagger2 API 离线文档

本文主要讲解如何在springboot下整合Swagger2 API离线文档。

本教程在Demo07基础上添加Swagger2 API离线文档配置信息

添加依赖

引入 springfox-staticdocs、spring-restdocs-mockmvc 依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-staticdocs</artifactId>
  <version>2.6.1</version>
  <scope>test</scope>
</dependency>

<dependency>
  <groupId>org.springframework.restdocs</groupId>
  <artifactId>spring-restdocs-mockmvc</artifactId>
  <version>2.0.2.RELEASE</version>
  <scope>test</scope>
</dependency>

MAVEN 属性配置

<swagger2markup.version>1.3.1</swagger2markup.version>
<swagger.output.dir>${project.build.directory}/asciidoc/json</swagger.output.dir>
<swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
<generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<swagger.input>${swagger.output.dir}/swagger.json</swagger.input>

添加插件配置

<!-- 以下用于生成adoc文件的配置 -->
<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>${swagger2markup.version}</version>
    <dependencies>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-import-files-ext</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <swaggerInput>${swagger.input}</swaggerInput>
        <outputDir>${generated.asciidoc.directory}</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
            <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}
            </swagger2markup.extensions.springRestDocs.snippetBaseUri>
            <swagger2markup.extensions.springRestDocs.defaultSnippets>true
            </swagger2markup.extensions.springRestDocs.defaultSnippets>
        </config>
    </configuration>
    <executions>
        <execution>
            <phase>test</phase>
            <goals>
                <goal>convertSwagger2markup</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<!--此插件生成HTML-->
<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>1.5.6</version>
  <configuration>
	<sourceDirectory>${generated.asciidoc.directory}</sourceDirectory>
	<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
	<headerFooter>true</headerFooter>
	<doctype>book</doctype>
	<backend>html</backend>
	<sourceHighlighter>coderay</sourceHighlighter>
	<attributes>
	  <!--菜单栏在左边-->
	  <toc>left</toc>
	  <!--多标题排列-->
	  <toclevels>3</toclevels>
	  <!--自动打数字序号-->
	  <sectnums>true</sectnums>
	</attributes>
  </configuration>
  <executions>
	<execution>
	  <phase>test</phase>
	  <goals>
		<goal>process-asciidoc</goal>
	  </goals>
	</execution>
  </executions>
</plugin>

编写测试类

在 com/heardfate/springboot/demo/Swagger2MarkupTest.java 下添加测试类

package com.heardfate.springboot.demo;

import org.junit.Before;
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.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import java.nio.file.Files;
import java.nio.file.Paths;

import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

  /**
   * @since: 2018/11/4
   * @author: Mr.HeardFate
   */
  @RunWith(SpringRunner.class)
  @SpringBootTest
  public class Swagger2MarkupTest {
	@Autowired
	private WebApplicationContext context;

	private MockMvc mockMvc;

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

	@Test
	public void createSpringfoxSwaggerJson() throws Exception {
	  String outputDir = "target/asciidoc/json";
	  //将api-docs的json数据写入文件
	  MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
		  .accept(MediaType.APPLICATION_JSON))
		  .andExpect(status().isOk())
		  .andReturn();

	  //将获取的JSON写入文件
	  MockHttpServletResponse response = mvcResult.getResponse();
	  String swaggerJson = response.getContentAsString();
	  Files.createDirectories(Paths.get(outputDir));
	  Files.write(Paths.get(outputDir, "swagger.json"), swaggerJson.getBytes());

	  //将多个ADOC整合成一个INDEX.ADOC文件
	  String generated = "target/asciidoc/generated";
	  Files.createDirectories(Paths.get(generated));
	  Files.write(Paths.get(generated, "index.adoc"), ("include::overview.adoc[]\ninclude::definitions" +
			".adoc[]\ninclude::paths.adoc[]").getBytes());
	}
}

运行测试

通过 Idea 的 Maven 窗口运行 test 命令，生成离线 HTML 文档

离线 API 文档