springboot+swagger导出文档

1maven配置

		
		
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        
        
        
            io.github.swagger2markup
            swagger2markup
            1.3.1
        
        
            nl.jworks.markdown_to_asciidoc
            markdown_to_asciidoc
            1.0
        
        
            org.pegdown
            pegdown
            1.6.0
            test
        

2.plugin 配置

            
                io.github.swagger2markup
                swagger2markup-maven-plugin
                1.3.1
                
                    
                    http://127.0.0.1:12306/v2/api-docs
                    src/docs/asciidoc/generated
                    
                        
                        ASCIIDOC
                    
                
            
            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.3
                
                
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        1.5.0-alpha.11
                    
                    
                        org.jruby
                        jruby-complete
                        1.7.21
                    
                
                
                
                    src/docs/asciidoc/generated
                    coderay
                    
                        left
                    
                
                
                
                    
                        output-html
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            html5
                            src/docs/asciidoc/html
                        
                    
                    
                        output-pdf
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            pdf
                            src/docs/asciidoc/pdf
                        
                    
                
            

3新建一个测试方法输出Ascii格式的文件

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.URL;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@SpringBootTest
public class CrmApplicationTests {
    
    @Test
    public void generateAsciiDocs() throws Exception {
        // 输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();
        Swagger2MarkupConverter.from(new URL("http://127.0.0.1:12306/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }
}

4配置SwaggerConfig文件

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
    }


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，才生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("com.gdqt.cloud.*.controller"))
            .paths(PathSelectors.any())
            .build()
            //在生产环境需要把swagger关闭，enable(false)
            .enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("XXX公司")
            .description("XXXCRM-API文档")
            .termsOfServiceUrl("http://www.baidu.com/")
            .version("1.0")
            .build();
    }
}

5.编译命令生成PDF，Html

1需要先启动项目，不然第三步测试方法访问接口不成功，无法生成Ascii格式文件。

2执行命令mvn asciidoctor:process-asciidoc

3Run 运行第三步测试方法generateAsciiDocs()，会生成Adoc文件。

4执行 命令 mvn generate-resources 生成PDF和HTML.

6 导出的pdf文件中文丢失和乱码的解决办法

解决问题的思路：

中文丢失或乱码，要么是编码或者是字体文件导致的，asciidoctor-maven-plugin导出PDF所依赖的asciidoctorj-pdf工具包，里面自带的字体文件对中文支持不是很好，只要将他的字体文件替换掉就可解决这个问题。

6.1先找到asciidoctorj-pdf在maven本地仓库下的jar。

6.2 打开jar包，找到font路径C:\Users\QTHJ.m2\repository\org\asciidoctor\asciidoctorj-pdf\1.5.0-alpha.11\aciidoctorj-pdf-1.5.0-alpha.11.jar\gems\asciidoctor-pdf-1.5.0.alpha.11\data\fonts\。添加上新的ttf文件，我这里添加的是楷体GB2312,这个可以在网上下载。

6.3修改主题配置文件，其路径在asciidoctorj-pdf-1.5.0-alpha.11.jar\gems\asciidoctor-pdf-1.5.0.alpha.11\data\themes。打开default-theme.yml文件，修改其字体配置文件后保存文件。

6.4重新生成PDF,查看效果。