swagger导出离线PDF API文档
基于swagger2makeup插件和asciidoctor来生成离线PDF Restful API文档。
起因
项目中使用swagger2来生成开发API文档,但是涉及到跨团队或者项目交付的时候,需要提供离线API文档,在尝试使用swagger导出离线文档的时候,发现baidu的很多文章基本上大同小异。
而且很多都要在项目中生成对应的离线asciidoc,在开发一个独立的Test case来进行,同时引入其他依赖到项目中,感觉对代码有侵入,本身业务也不需要这些依赖,发现结合自己项目很多东西都要修改,后面发现可以通过swagger2makeup来在客户端通过命令行来实现,也是非常简单同时还不用侵入代码,特意记录起来分享。
离线文档生成
根据swagger2markup在当前目录下生成文件名为“swagger-doc.adoc”的asciidoc文件。本文中使用docker镜像来创建adoc文件,也可以参考官网来通过jar来生成。
docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i "http://192.168.101.6:8016/v2/api-docs" -f /opt/swagger-doc
如果是已经生成的本地json文件也可以替换url链接为json文件,例如本地/tmp/swagger.json
docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /tmp/swagger.json -f /opt/swagger-doc
根据产生的adoc文件在当前目录下生成名为“swagger-doc.pdf”的文档。
docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf swagger-doc.adoc
http://192.168.101.6:8016/v2/api-docs 地址内容这里只展示部分内容
{
swagger: "2.0",
info:- {
description: "Api Documentation",
version: "1.0",
title: "Api Documentation",
termsOfService: "urn:tos",
contact:{},
license:- {
name: "Apache 2.0",
url: "<http://www.apache.org/licenses/LICENSE-2.0>"
}
},
host: "192.168.101.6:8016",
basePath: "/",
tags:+ [... ],
执行完成效果查看
qujianfei@troyMac ~/docker/swagger_dir ls
qujianfei@troyMac ~/docker/swagger_dir docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i "http://192.168.101.6:8016/v2/api-docs" -f /opt/swagger-doc
06:09:13.641 [main] INFO io.swagger.parser.Swagger20Parser - reading from http://192.168.101.6:8016/v2/api-docs
06:09:15.965 [main] DEBUG i.g.s.i.document.PathsDocument - Generate examples is disabled.
06:09:15.965 [main] DEBUG i.g.s.i.document.PathsDocument - Create separated operation files is disabled.
06:09:15.971 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Create separated definition files is disabled.
06:09:16.836 [main] INFO i.g.s.m.b.i.asciidoc.AsciiDocBuilder - Markup document written to: /opt/swagger-doc.adoc
06:09:17.237 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'linksUsingGET' (normalized id = 'linksUsingGET')
06:09:17.288 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'handleUsingGET_2' (normalized id = 'handleUsingGET_2')
06:09:17.333 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'handleUsingGET_1' (normalized id = 'handleUsingGET_1')
06:09:17.455 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'handleUsingGET' (normalized id = 'handleUsingGET')
06:09:17.554 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'handleUsingGET_3' (normalized id = 'handleUsingGET_3')
06:09:17.680 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'addMonitorPluginUsingPUT_1' (normalized id = 'addMonitorPluginUsingPUT_1')
06:09:17.738 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'tokenValidateUsingPOST_1' (normalized id = 'tokenValidateUsingPOST_1')
06:09:17.774 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingPOST' (normalized id = 'errorHtmlUsingPOST')
06:09:17.807 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingGET' (normalized id = 'errorHtmlUsingGET')
06:09:17.841 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingPUT' (normalized id = 'errorHtmlUsingPUT')
06:09:17.884 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingDELETE' (normalized id = 'errorHtmlUsingDELETE')
06:09:17.907 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingPATCH' (normalized id = 'errorHtmlUsingPATCH')
06:09:17.931 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingHEAD' (normalized id = 'errorHtmlUsingHEAD')
06:09:17.963 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'errorHtmlUsingOPTIONS' (normalized id = 'errorHtmlUsingOPTIONS')
06:09:18.068 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getAgentUsingGET' (normalized id = 'getAgentUsingGET')
06:09:18.121 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'uploadAgentUsingPOST' (normalized id = 'uploadAgentUsingPOST')
06:09:18.157 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'uploadProxyUsingPOST' (normalized id = 'uploadProxyUsingPOST')
06:09:18.200 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getProxyUsingGET' (normalized id = 'getProxyUsingGET')
06:09:18.243 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'updateAgentStatusUsingPOST' (normalized id = 'updateAgentStatusUsingPOST')
06:09:18.291 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'createAgentsUsingPUT' (normalized id = 'createAgentsUsingPUT')
06:09:18.343 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAgentsUsingGET_2' (normalized id = 'listAgentsUsingGET_2')
06:09:18.374 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'createAgentUsingPUT' (normalized id = 'createAgentUsingPUT')
06:09:18.414 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'addMonitorPluginUsingPUT' (normalized id = 'addMonitorPluginUsingPUT')
06:09:18.443 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getPluginListUsingGET' (normalized id = 'getPluginListUsingGET')
06:09:18.498 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'tokenValidateUsingPOST' (normalized id = 'tokenValidateUsingPOST')
06:09:18.535 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'heartBeatUsingPOST' (normalized id = 'heartBeatUsingPOST')
06:09:18.590 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getInstallerUsingGET' (normalized id = 'getInstallerUsingGET')
06:09:18.624 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAgentsUsingGET' (normalized id = 'listAgentsUsingGET')
06:09:18.649 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAllPluginInstallerUsingGET' (normalized id = 'listAllPluginInstallerUsingGET')
06:09:18.671 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'updatePluginsUsingPATCH' (normalized id = 'updatePluginsUsingPATCH')
06:09:18.733 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getAgentDetailByResIdUsingGET' (normalized id = 'getAgentDetailByResIdUsingGET')
06:09:18.780 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'deleteAgentByResourceIdsUsingDELETE' (normalized id = 'deleteAgentByResourceIdsUsingDELETE')
06:09:18.796 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAgentStatesUsingGET' (normalized id = 'listAgentStatesUsingGET')
06:09:18.845 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getTopUpTimeUsingGET' (normalized id = 'getTopUpTimeUsingGET')
06:09:18.863 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'agentDetailUsingGET' (normalized id = 'agentDetailUsingGET')
06:09:18.900 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'deleteAgentUsingDELETE' (normalized id = 'deleteAgentUsingDELETE')
06:09:18.927 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAgentsUsingGET_1' (normalized id = 'listAgentsUsingGET_1')
06:09:18.958 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'cancelUsingGET' (normalized id = 'cancelUsingGET')
06:09:19.027 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'runUsingPOST' (normalized id = 'runUsingPOST')
06:09:19.088 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'countUsingGET' (normalized id = 'countUsingGET')
06:09:19.105 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'countsUsingGET' (normalized id = 'countsUsingGET')
06:09:19.127 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listUsingGET' (normalized id = 'listUsingGET')
06:09:19.145 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'detailUsingGET' (normalized id = 'detailUsingGET')
06:09:19.174 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'deleteUsingDELETE' (normalized id = 'deleteUsingDELETE')
06:09:19.197 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'cancelUsingPOST' (normalized id = 'cancelUsingPOST')
06:09:19.234 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'createUsingPUT' (normalized id = 'createUsingPUT')
06:09:19.282 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'countUsingGET_1' (normalized id = 'countUsingGET_1')
06:09:19.319 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'detailUsingGET_1' (normalized id = 'detailUsingGET_1')
06:09:19.351 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'deleteUsingDELETE_1' (normalized id = 'deleteUsingDELETE_1')
06:09:19.406 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'updateUsingPATCH' (normalized id = 'updateUsingPATCH')
06:09:19.468 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'cancelUsingPOST_1' (normalized id = 'cancelUsingPOST_1')
06:09:19.529 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'runUsingPOST_1' (normalized id = 'runUsingPOST_1')
06:09:19.572 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listUsingGET_1' (normalized id = 'listUsingGET_1')
06:09:19.633 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'getExecutionLogUsingGET' (normalized id = 'getExecutionLogUsingGET')
06:09:19.743 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'createUsingPUT_1' (normalized id = 'createUsingPUT_1')
06:09:19.800 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'changeFileToStringUsingGET' (normalized id = 'changeFileToStringUsingGET')
06:09:19.841 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'checkedListUsingGET' (normalized id = 'checkedListUsingGET')
06:09:19.956 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'runScriptUsingPOST' (normalized id = 'runScriptUsingPOST')
06:09:20.011 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'detailUsingGET_2' (normalized id = 'detailUsingGET_2')
06:09:20.074 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'deleteUsingDELETE_2' (normalized id = 'deleteUsingDELETE_2')
06:09:20.111 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'updateUsingPATCH_1' (normalized id = 'updateUsingPATCH_1')
06:09:20.126 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'contentUsingGET' (normalized id = 'contentUsingGET')
06:09:20.152 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'checkUsingPOST' (normalized id = 'checkUsingPOST')
06:09:20.163 [main] DEBUG i.g.s.i.document.PathsDocument - Operation processed : 'listAllScriptsUsingGET' (normalized id = 'listAllScriptsUsingGET')
06:09:20.218 [main] INFO i.g.s.m.b.i.asciidoc.AsciiDocBuilder - Markup document written to: /opt/swagger-doc.adoc
06:09:20.235 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Agent'
06:09:20.255 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'AgentParam'
06:09:20.257 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'AgentPlugin'
06:09:20.266 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'AgentPluginBinding'
06:09:20.271 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ExecDetailView'
06:09:20.279 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ExecutionConditionCounts'
06:09:20.280 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ExecutionItem'
06:09:20.291 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ExecutionListView'
06:09:20.302 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'HeartBeat'
06:09:20.304 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'JobDetailView'
06:09:20.308 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'JobItem'
06:09:20.314 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'JobListView'
06:09:20.317 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'JobNode'
06:09:20.320 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'JobRequest'
06:09:20.335 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Link'
06:09:20.336 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'LogEntry'
06:09:20.339 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'LogView'
06:09:20.341 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Map«string,Link»'
06:09:20.343 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Map«string,long»'
06:09:20.345 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Map«string,string»'
06:09:20.350 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ModelAndView'
06:09:20.354 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Node'
06:09:20.361 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'NodeStepState'
06:09:20.368 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Option'
06:09:20.373 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'PagedResultBean«SmartAgent»'
06:09:20.375 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'PluginParam'
06:09:20.378 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean'
06:09:20.388 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«AgentPluginBinding»'
06:09:20.392 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«AgentPlugin»'
06:09:20.393 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«Agent»'
06:09:20.394 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ExecDetailView»'
06:09:20.399 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ExecutionItem»'
06:09:20.407 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ExecutionListView»'
06:09:20.410 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«JobDetailView»'
06:09:20.411 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«JobListView»'
06:09:20.413 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«AgentPlugin»»'
06:09:20.415 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«ExecutionConditionCounts»»'
06:09:20.420 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«Map«string,long»»»'
06:09:20.424 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«Script»»'
06:09:20.428 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«SmartAgent»»'
06:09:20.433 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«List«string»»'
06:09:20.436 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«LogView»'
06:09:20.440 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«Map«string,string»»'
06:09:20.444 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ScriptContent»'
06:09:20.446 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ScriptDetailView»'
06:09:20.450 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«ScriptListView»'
06:09:20.452 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«SmartAgent»'
06:09:20.454 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«int»'
06:09:20.455 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«long»'
06:09:20.458 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ResultBean«string»'
06:09:20.459 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'RunCmdParam'
06:09:20.463 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'RunScriptParam'
06:09:20.475 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Script'
06:09:20.484 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ScriptContent'
06:09:20.487 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ScriptDetailView'
06:09:20.492 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ScriptItem'
06:09:20.501 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'ScriptListView'
06:09:20.510 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'SmartAgent'
06:09:20.516 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'TokenValidateParam'
06:09:20.522 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'View'
06:09:20.529 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'Workflow'
06:09:20.531 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'WorkflowStep'
06:09:20.537 [main] DEBUG i.g.s.i.document.DefinitionsDocument - Definition processed : 'WorkflowWorkflowStep'
06:09:20.562 [main] INFO i.g.s.m.b.i.asciidoc.AsciiDocBuilder - Markup document written to: /opt/swagger-doc.adoc
06:09:20.573 [main] INFO i.g.s.m.b.i.asciidoc.AsciiDocBuilder - Markup document written to: /opt/swagger-doc.adoc
qujianfei@troyMac ~/docker/swagger_dir ls
swagger-doc.adoc
qujianfei@troyMac ~/docker/swagger_dir docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf swagger-doc.adoc
qujianfei@troyMac ~/docker/swagger_dir ls
swagger-doc.adoc swagger-doc.pdf
qujianfei@troyMac ~/docker/swagger_dir
查看pdf文件
swagger配置
build.gradle
implementation 'io.springfox:springfox-swagger2:2.9.2'
compile group: 'com.github.xiaoymin', name: 'swagger-bootstrap-ui', version: '1.9.6'
spring配置类
package com.troy.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
swagger配置这里只粘贴了项目中的部分代码,实际使用中不需要和保持一致,只要引入swagger2可以生成swagger json文件即可。
结尾
整体使用下来发现,基于swagger2makeup插件和asciidoctor生成离线文档的方式操作简单并且代码侵入性小,而且几乎没有学习成本,可以做到即插即用,可以完全满足一般需求。但是本次示例也有一些遗留问题,就是对于pdf的字体的配置,这个本次就不在做过多探究了,后面如果有时间在继续探索字体的设置,也欢迎哪位同学如果有方案也可以一起探讨。