spring+swagger2生成在线文档，以及离线pdf文档

maven依赖

        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        

        
        
            io.github.swagger2markup
            swagger2markup
            1.3.1
        
        
    

swagger2配置文件

package com.jincheng.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: jinCheng
 * @description: swagger2配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.enable:true}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)
                .apiInfo(apiInfo())
                .select()
                // 此处换成自己项目的扫描包
                .apis(RequestHandlerSelectors.basePackage("com.jincheng"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("示例 APIs")
                .version("1.0")
                .build();
    }
}

java代码生成asciidoc文件

package com.jincheng;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Paths;

/**
 * @author: jinCheng
 * @description: java代码生成文档
 */
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class Swagger2Tests {

    /**
     * 获取项目在线swagger的json数据,8099,修改为自己项目设置的
     */
    private String swagger_source_url = "http://localhost:8099/v2/api-docs";

    /**
     * 生成的asciidoc文件的存放目录
     */
    private String asciidoc_dir = "src/main/resources/docs/asciidoc/generated";

    private String fileName = "all";

    /**
     * 生成AsciiDocs格式文档
     *
     * @throws MalformedURLException
     */
    @Test
    public void generateAsciiDoc() throws MalformedURLException {
        // MarkupLanguage三种格式:ASCIIDOC,MARKDOWN,CONFLUENCE_MARKUP
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL(swagger_source_url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get(asciidoc_dir));
    }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     *
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(swagger_source_url))
                .withConfig(config)
                .build()
                .toFile(Paths.get(asciidoc_dir + "/" + fileName));
    }
}

maven插件生成asciidoc

路径配置

    
        1.8
        
        http://localhost:8099/v2/api-docs
        
        src/main/resources/docs/asciidoc/generated
        
        src/main/resources/docs/html/generated
        
        src/main/resources/docs/pdf/generated
    

maven插件

 
            
            
                io.github.swagger2markup
                swagger2markup-maven-plugin
                1.3.1
                
                    ${swagger_source_url}
                    ${asciidoc_output_directory}
                    
                        ASCIIDOC
                    
                
            

maven插件生成离线pdf文档

插件信息

            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.6

                
                
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        
                        1.5.0-alpha-zh.16
                    
                    
                        org.jruby
                        jruby-complete
                        1.7.21
                    
                

                
                    
                    ${asciidoc_output_directory}
                    coderay
                    
                        
                        left
                        
                        3
                        
                        true
                    
                

                
                    
                        output-html
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            html5
                            
                            ${html_output_directory}
                        
                    

                    
                        output-pdf
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            pdf
                            
                            ${pdf_output_directory}
                            
                            
                                cn
                            
                        
                    
                
            

生成pdf中文缺字问题

下载jar

https://gitee.com/jincheng-921/asciidoctorj-pdf-jar.git

上传到maven本地仓库，私服

https://blog.csdn.net/jincheng_921/article/details/89504440

项目源码

https://gitee.com/jincheng-921/spring_swagger2_demo.git
项目启动后查看在线文档 http://localhost:8099/swagger-ui.html