swagger导出离线API文档 swagger导出离线PD

发表于

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来生成。

swagger2markup jar生成文档

swagger2markup cli地址

1
sh复制代码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

1
sh复制代码docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /tmp/swagger.json -f /opt/swagger-doc

根据产生的adoc文件在当前目录下生成名为“swagger-doc.pdf”的文档。

1
sh复制代码docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf swagger-doc.adoc

http://192.168.101.6:8016/v2/api-docs 地址内容这里只展示部分内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
json复制代码{

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:+ [... ],

执行完成效果查看

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
sh复制代码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.png

swagger配置

build.gradle

1
2
yaml复制代码    implementation 'io.springfox:springfox-swagger2:2.9.2'
    compile group: 'com.github.xiaoymin', name: 'swagger-bootstrap-ui', version: '1.9.6'

spring配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
java复制代码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的字体的配置，这个本次就不在做过多探究了，后面如果有时间在继续探索字体的设置，也欢迎哪位同学如果有方案也可以一起探讨。

本文转载自: 掘金

开发者博客 – 和开发相关的 这里全都有

0%