springboot+swagger导出文档

深碍√TFBOYSˉ_ 2021-10-18 22:34 761阅读 0赞

### 1maven配置 ###

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>
            
            <dependency>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup</artifactId>
                <version>1.3.1</version>
            </dependency>
            <dependency>
                <groupId>nl.jworks.markdown_to_asciidoc</groupId>
                <artifactId>markdown_to_asciidoc</artifactId>
                <version>1.0</version>
            </dependency>
            <dependency>
                <groupId>org.pegdown</groupId>
                <artifactId>pegdown</artifactId>
                <version>1.6.0</version>
                <scope>test</scope>
            </dependency>

### 2.plugin 配置 ###

<plugin>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-maven-plugin</artifactId>
                    <version>1.3.1</version>
                    <configuration>
                        
                        <swaggerInput>http://127.0.0.1:12306/v2/api-docs</swaggerInput>
                        <outputDir>src/docs/asciidoc/generated</outputDir>
                        <config>
                            
                            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        </config>
                    </configuration>
                </plugin>
                
                <plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.3</version>
                    
                    <dependencies>
                        <dependency>
                            <groupId>org.asciidoctor</groupId>
                            <artifactId>asciidoctorj-pdf</artifactId>
                            <version>1.5.0-alpha.11</version>
                        </dependency>
                        <dependency>
                            <groupId>org.jruby</groupId>
                            <artifactId>jruby-complete</artifactId>
                            <version>1.7.21</version>
                        </dependency>
                    </dependencies>
                    
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                        <sourceHighlighter>coderay</sourceHighlighter>
                        <attributes>
                            <toc>left</toc>
                        </attributes>
                    </configuration>
                    
                    <executions>
                        <execution>
                            <id>output-html</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>html5</backend>
                                <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                            </configuration>
                        </execution>
                        <execution>
                            <id>output-pdf</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>pdf</backend>
                                <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>

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

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70]

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

###### 解决问题的思路： ######

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

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

![在这里插入图片描述][20190813114325917.png]

##### 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,这个可以在网上下载。 #####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 1]

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

![在这里插入图片描述][20190813115236587.png]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 2]

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

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 3]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70]: /images/20211018/cc004756aa984852852cf52484f3904d.png
[20190813114325917.png]: /images/20211018/de8cb54e7c454691bfc094e1be6df6bf.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 1]: /images/20211018/1367a4db7b5b4548be940bd9e04c7e1d.png
[20190813115236587.png]: /images/20211018/20d96d9845f84634a32de8c655788f5e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 2]: /images/20211018/46d786ce9885497fa0a6794353a78173.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMwNTUzNzcz_size_16_color_FFFFFF_t_70 3]: /images/20211018/8bccf24716e74ec88fa23ebf427e1a31.png