Spring boot 2.1.3+Swagger2.9.2+swagger2markup生成离线HTML和pdf接口文档

Swagger2.9.2生成离线HTML接口文档

因为Swagger版本升级，导致以前的离线HTML接口文档无法使用，因此用了两天时间，重新研究。

1、接口文档展示

先展示一张最终效果图：

2、目的

      配置到Springboot项目中以后，在项目打包的时候便会通过单元测试在指定的目录生成被官方称为staticdocs的离线文档

3、开始配置

1、Maven依赖引入

(1).properties设置

<properties>
		<java.version>1.8</java.version>
		<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
		<swagger2markup.version>1.2.0</swagger2markup.version>
		<asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
		<swagger.output.dir>${project.build.directory}/swagger</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>
		<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
		<swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
	</properties>

（2）repositories加载

<repositories>
		<repository>
			<id>jcentral</id>
			<name>bintray</name>
			<url>http://jcenter.bintray.com</url>
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
		</repository>
		<repository>
			<id>jcenter-snapshots</id>
			<name>jcenter</name>
			<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
		</repository>
	</repositories>

（3）dependency依赖 

<!--offline doc-->
<dependency>
   <groupId>org.springframework.restdocs</groupId>
   <artifactId>spring-restdocs-mockmvc</artifactId>
   <!--<version>2.0.2.RELEASE</version>-->
   <!--<scope>test</scope>-->
</dependency>
<dependency>
   <groupId>io.github.swagger2markup</groupId>
   <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
   <version>${swagger2markup.version}</version>
   <scope>test</scope>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-staticdocs</artifactId>
   <version>2.6.1</version>
   <!--<scope>test</scope>-->
</dependency>

2、asciidoctor-maven-plugin插件引入，生成把Asciidoc格式文件转成HTML5格式输出。

<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.3</version>
				<configuration>
					<compilerVersion>${java.version}</compilerVersion>
					<source>${java.version}</source>
					<target>${java.version}</target>
					<encoding>UTF-8</encoding>
					<!-- prevents endPosTable exception for maven compile -->
					<useIncrementalCompilation>false</useIncrementalCompilation>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-surefire-plugin</artifactId>
				<configuration>
					<systemPropertyVariables>
						<io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
						<io.springfox.staticdocs.snippetsOutputDir>${swagger.snippetOutput.dir}</io.springfox.staticdocs.snippetsOutputDir>
					</systemPropertyVariables>
				</configuration>
			</plugin>

			<!-- First, use the swagger2markup plugin to generate asciidoc -->
			<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.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
						<swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
						<swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
						<swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>

						<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>

			<!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
			<plugin>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctor-maven-plugin</artifactId>
				<version>1.5.6</version>
				<!-- Include Asciidoctor PDF for pdf generation -->
				<dependencies>
					<dependency>
						<groupId>org.asciidoctor</groupId>
						<artifactId>asciidoctorj-pdf</artifactId>
						<version>1.5.0-alpha.16</version>
					</dependency>
					<dependency>
						<groupId>org.jruby</groupId>
						<artifactId>jruby-complete</artifactId>
						<version>1.7.21</version>
					</dependency>
				</dependencies>
				<!-- Configure generic document generation settings -->
				<configuration>
					<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
					<sourceDocumentName>index.adoc</sourceDocumentName>
					<attributes>
						<doctype>book</doctype>
						<toc>left</toc>
						<toclevels>3</toclevels>
						<numbered></numbered>
						<hardbreaks></hardbreaks>
						<sectlinks></sectlinks>
						<sectanchors></sectanchors>
						<generated>${generated.asciidoc.directory}</generated>
					</attributes>
				</configuration>
				<!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
				<executions>
					<execution>
						<id>output-html</id>
						<phase>test</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>html5</backend>
							<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
						</configuration>
					</execution>

					<execution>
						<id>output-pdf</id>
						<phase>test</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>pdf</backend>
							<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
						</configuration>
					</execution>

				</executions>
			</plugin>

			<!-- specify the main class for the manifest -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-jar-plugin</artifactId>
				<version>3.1.0</version>
				<configuration>
					<archive>
						<manifest>
							<addClasspath>true</addClasspath>
							<classpathPrefix>lib/</classpathPrefix>
							<!--important!!! specify the main class for the manifest!!!-->
							<!--important!!! specify the main class for the manifest!!!-->
							<!--important!!! specify the main class for the manifest!!!-->
							<mainClass>com.chinamobile.cmic.apidoc.ApiDocApplication</mainClass>
						</manifest>
					</archive>
				</configuration>
			</plugin>

			<!-- copy dependencies to the lib directory -->
			<plugin>
				<artifactId>maven-dependency-plugin</artifactId>
				<executions>
					<execution>
						<phase>package</phase>
						<goals>
							<goal>copy-dependencies</goal>
						</goals>
						<configuration>
							<outputDirectory>${project.build.directory}/lib</outputDirectory>
						</configuration>
					</execution>
				</executions>
			</plugin>

			<!-- copy the generated documents -->
			<plugin>
				<artifactId>maven-resources-plugin</artifactId>
				<version>3.1.0</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>${asciidoctor.html.output.directory}</directory>
								</resource>
								<resource>
									<directory>${asciidoctor.pdf.output.directory}</directory>
								</resource>
							</resources>
						</configuration>
					</execution>
				</executions>
			</plugin>

3、根据Swagger接口自动生成单元测试

package com.unicom.lgbsmp;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.restdocs.operation.preprocess.Preprocessors;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;

import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;


/**
 * @author ChaselX
 * @date 2019/1/29 13:02
 */
@WebAppConfiguration
@RunWith(SpringRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
@SpringBootTest
@AutoConfigureMockMvc
public class Documentation {
    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testApi() throws Exception {
        mockMvc.perform(get("/greeting")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(document("greetingGet",
                        Preprocessors.preprocessResponse(Preprocessors.prettyPrint()))).andReturn();
               // .andExpect(status().isOk());
    }

    @Test
    public void createSpringfoxSwaggerJson() throws Exception {

        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
               // .andExpect(status().isOk())
                .andReturn();

        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }
}

4、index.adoc创建

 项目路径：src/docs/asciidoc/index.adoc

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::{generated}/definitions.adoc[]

5、运行

（1）第一步先获取在线版本的文档并保存到文件swagger.json中，运行Documentation.class生成swagger.json

(2) 第二步把swagger.json和之前的例子snippets整合并保存为Asciidoc格式的完整文档。执行package命令生成结果如图：

扫描二维码关注公众号，回复： 5981504 查看本文章