导出Swagger2接口文档为PDF

导出Swagger2接口文档为PDF

1.导出pdf

1. 首先使用springboot+swagger2，搭建好基础环境，过程比较简单，不再赘述。启动项目后访问swagger2接口文档，访问成功即可。
2. 在pom.xml中添加依赖

  <!-- 指定远程仓库 -->
  <repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>

 
   <dependencies>
  		...
  		<!-- 导出pdf -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
   </dependencies>

  <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.11</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                    <backend>pdf</backend>
                </configuration>
            </plugin>
        </plugins>

3. 修改SwaggerConfig配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zgs.testmvc.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("swagger2 文档")
                        .description("测试版")
                        .version("1.0")
                        //联系信息
                        .contact(new Contact("啊","blog.csdn.net","aaa@gmail.com"))
                        //认证信息
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .termsOfServiceUrl("http://www.1111.com")
                        .build());
    }

    @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/");
    }
}

4. 在test中编写测试一个测试类

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class AppPdfTest {
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();
 		//此处填写swagger项目地址
        Swagger2MarkupConverter.from(new URL("http://127.0.0.1:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/all"));
    }
}

此时,maven中应该包含pom中依赖的插件

5. 首先执行maven 中的 test，执行成功后，再执行AppPdfTest的方法,执行成功后，会在src/docs/asciidoc/generated目录下生成all.adoc文件；然后，在maven-plugins中，双击执行asciidoctor：process-asciidoc。执行成功后，在src/docs/asciidoc/pdf目录下生成all.pdf文件，此文件就是需要的pdf文档。

2. 解决中文问题

1. 因为插件对中文支持不好，解决办法：首先下载中文字库.ttl文件，可在网上下载需要的字体文件。

2. 找到maven中依赖的插件所在的本地仓库位置：例如我的是在D:\repo\org\asciidoctor\asciidoctorj-pdf\1.5.0-alpha.11。将下载的字体文件，添加到该压缩包中指定位置:asciidoctorj-pdf-1.5.0-alpha.11.jar\gems\asciidoctor-pdf-1.5.0.alpha.11\data\fonts
   

3. 修改asciidoctorj-pdf-1.5.0-alpha.11.jar\gems\asciidoctor-pdf-1.5.0.alpha.11\data\themes下的default-theme.yml文件
   

4. 修改完成后，在按照生成步骤，重新生成pdf即可。

5. 导出的效果：
   

总结

主要步骤：

1. 第一步首先搭建好swagger2的环境，可以正常访问swagger。
2. pom文件中添加依赖
3. 运行测试类，根据http://127.0.0.1:8080/v2/api-docs返回的json数据，创建all.adoc文件
4. 执行maven–>plugins–>…–>process-asciidoc,生成pdf文件