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

		1.8
		${project.build.directory}/generated-snippets
		1.2.0
		${project.basedir}/src/docs/asciidoc
		${project.build.directory}/swagger
		${project.build.directory}/asciidoc/snippets
		${project.build.directory}/asciidoc/generated
		${project.build.directory}/asciidoc/html
		${project.build.directory}/asciidoc/pdf
		${swagger.output.dir}/swagger.json
	

（2）repositories加载

		
			jcentral
			bintray
			http://jcenter.bintray.com
			
				false
			
		
		
			jcenter-snapshots
			jcenter
			http://oss.jfrog.org/artifactory/oss-snapshot-local/
		
	

（3）dependency依赖 

   org.springframework.restdocs
   spring-restdocs-mockmvc
   
   


   io.github.swagger2markup
   swagger2markup-spring-restdocs-ext
   ${swagger2markup.version}
   test


   io.springfox
   springfox-staticdocs
   2.6.1
   

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

				org.apache.maven.plugins
				maven-compiler-plugin
				3.3
				
					${java.version}
					${java.version}
					${java.version}
					UTF-8
					
					false
				
			
			
				org.apache.maven.plugins
				maven-surefire-plugin
				
					
						${swagger.output.dir}
						${swagger.snippetOutput.dir}
					
				
			

			
			
				io.github.swagger2markup
				swagger2markup-maven-plugin
				${swagger2markup.version}
				
					
						io.github.swagger2markup
						swagger2markup-import-files-ext
						${swagger2markup.version}
					
					
						io.github.swagger2markup
						swagger2markup-spring-restdocs-ext
						${swagger2markup.version}
					
				
				
					${swagger.input}
					${generated.asciidoc.directory}
					
						ASCIIDOC
						TAGS

						${project.basedir}/src/docs/asciidoc/extensions/overview
						${project.basedir}/src/docs/asciidoc/extensions/definitions
						${project.basedir}/src/docs/asciidoc/extensions/paths
						${project.basedir}src/docs/asciidoc/extensions/security/

						${swagger.snippetOutput.dir}
						true
					
				
				
					
						test
						
							convertSwagger2markup
						
					
				
			

			
			
				org.asciidoctor
				asciidoctor-maven-plugin
				1.5.6
				
				
					
						org.asciidoctor
						asciidoctorj-pdf
						1.5.0-alpha.16
					
					
						org.jruby
						jruby-complete
						1.7.21
					
				
				
				
					${asciidoctor.input.directory}
					index.adoc
					
						book
						left
						3
						
						
						
						
						${generated.asciidoc.directory}
					
				
				
				
					
						output-html
						test
						
							process-asciidoc
						
						
							html5
							${asciidoctor.html.output.directory}
						
					

					
						output-pdf
						test
						
							process-asciidoc
						
						
							pdf
							${asciidoctor.pdf.output.directory}
						
					

				
			

			
			
				org.apache.maven.plugins
				maven-jar-plugin
				3.1.0
				
					
						
							true
							lib/
							
							
							
							com.chinamobile.cmic.apidoc.ApiDocApplication
						
					
				
			

			
			
				maven-dependency-plugin
				
					
						package
						
							copy-dependencies
						
						
							${project.build.directory}/lib
						
					
				
			

			
			
				maven-resources-plugin
				3.1.0
				
					
						copy-resources
						prepare-package
						
							copy-resources
						
						
							${project.build.outputDirectory}/static/docs
							
								
									${asciidoctor.html.output.directory}
								
								
									${asciidoctor.pdf.output.directory}
								
							
						
					
				
			

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 : 贾涛
 * @date : 2019/4/22  14:23
 */
@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命令生成结果如图：