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 下添加测试类

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


离线 API 文档