SpringBoot2 + Swagger2 + Swagger2Markup-cli + asciidoctor 生成swagger的pdf文档

最近遇到了需要将Swagger的API文档导出pdf发送给其他对接的开发人员的工作。为了实现这个功能，阅读了很多优秀的文章，同时也找到不错的工具，当然也从同事那里得到了很多帮助。把这些信息整理并记录下来，如果你也遇到了类似的需求，希望可以帮助你节约很多时间。

userful website collection

springboot+swagger接口文档企业实践 这篇文章的主人详细介绍了springboot+swagger在企业级应用场景下的实践方案，如果有时间建议详细阅读这篇文章或者是swagger的官方文档

swagger2markup-cli github repo 这是Swagger2Markup提供的cli工具，我更推荐你使用cli工具而非侵入式maven / gradle plugin过程

asciidoctor 这个工具用来将二进制文件转换为html5页面或者doc文档，pdf文档

Let’s do this

1. Step One : 为项目增加swagger依赖并查看项目使用的swagger文档

在原有的springboot项目中增加springfox-swagger和springfox-swagger-ui依赖，如果你使用的是maven，代码是这样的：

		
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger2artifactId>
			<version>2.8.0version>
		dependency>
		<dependency>
			<groupId>io.springfoxgroupId>
			<artifactId>springfox-swagger-uiartifactId>
			<version>2.8.0version>
		dependency>

如果你使用的是gradle，代码是这样的:

dependencies {
    // swagger
    implementation "io.springfox:springfox-swagger2:${swaggerVersion}"
    implementation "io.springfox:springfox-swagger-ui:${swaggerVersion}"
}

同时需要为Springboot项目增加相关配置，在恰当的位置新建swagger config的类，具体内容如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Your swagger API title")
                .description("Description: Your swagger API description")
                .contact(new Contact("", "", ""))
                .version("0.0.1")
                .build();
    }
}

完成了上述配置之后，启动你的项目，在你的项目中输入项目启动的端口号+/swagger-ui.html就可以看到相应的swagger-ui内容了。

2. Step Two：下载swagger.json文件并通过swagger2markup-cli进行二进制文件映射

在成功的在本地启动的服务器中打开swagger定义信息后，你可以通过swagger2markup的cli工具将swagger.json文件映射成二进制文件。这里我建议你使用swagger2markup-cli工具，在Mac操作系统中可以通过homebrew进行安装。

brew install swagger2markup-cli

首先你需要将swagger.json文件下载到本地。在恰当的目录执行以下代码：

curl -o swagger.json http://localhost:8080/v2/api-docs

然后通过swagger2markup-cli工具将swagger.json文件进行二进制映射。

swagger2markup convert -i swagger.json -d ./markup-out/

这时可以看到生成了映射目录 ./markup-out/，其中的目录结构大致如下：

definitions.adoc overview.adoc    paths.adoc       security.adoc

swagger.json文件被分成了几个孤立的文件，如果我们需要将他们合并在一起，可以自己创建一个index.adoc文件，内容大概如下：

include::overview.adoc[]
include::paths.adoc[]
include::definitions.adoc[]

3. Step Three：利用asciidocotr将二进制文件生成pdf文档

安装asciidoctor工具：

brew install asciidoctor

进入./markup-out/目录下执行：

asciidoctor-pdf index.adoc

就可以把index.adoc文件生成index.pdf文件了