最近遇到了需要将Swagger的API文档导出pdf发送给其他对接的开发人员的工作。为了实现这个功能,阅读了很多优秀的文章,同时也找到不错的工具,当然也从同事那里得到了很多帮助。把这些信息整理并记录下来,如果你也遇到了类似的需求,希望可以帮助你节约很多时间。
springboot+swagger接口文档企业实践 这篇文章的主人详细介绍了springboot+swagger在企业级应用场景下的实践方案,如果有时间建议详细阅读这篇文章或者是swagger的官方文档
swagger2markup-cli github repo 这是Swagger2Markup提供的cli工具,我更推荐你使用cli工具而非侵入式maven / gradle plugin过程
asciidoctor 这个工具用来将二进制文件转换为html5页面或者doc文档,pdf文档
在原有的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内容了。
在成功的在本地启动的服务器中打开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[]
安装asciidoctor工具:
brew install asciidoctor
进入./markup-out/目录下执行:
asciidoctor-pdf index.adoc
就可以把index.adoc文件生成index.pdf文件了