Swagger2 生成 html 、pdf 离线文档
源码地址：
https://github.com/tanzj520/SwaggerDocDemo
首先，在项目pom中引入依赖 (我这里直接贴上完整的pom)
4.0.0
com.tanzj
SwaggerDocDemo
1.0-SNAPSHOT
org.springframework.boot
spring-boot-starter-parent
1.5.6.RELEASE
UTF-8
UTF-8
1.8
1.3.1
1.3.3
1.3.1
1.5.5
1.5.0-alpha.15
9.1.8.0
${project.basedir}/src/docs/swagger/swagger.json
${project.basedir}/src/docs/asciidoc
${project.build.directory}/asciidoc
${project.build.directory}/asciidoc/html
${project.build.directory}/asciidoc/pdf
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-test
test
io.springfox
springfox-staticdocs
2.6.1
test
org.springframework.restdocs
spring-restdocs-mockmvc
test
jcenter-snapshots
jcenter
http://oss.jfrog.org/artifactory/oss-snapshot-local/
false
jcenter-releases
jcenter
http://jcenter.bintray.com
SwaggerDocDemo
org.springframework.boot
spring-boot-maven-plugin
org.apache.maven.plugins
maven-war-plugin
2.1.1
${project.basedir}/lib
WEB-INF/lib
false
**/*.jar
org.apache.maven.plugins
maven-compiler-plugin
1.8
1.8
org.apache.maven.plugins
maven-surefire-plugin
2.18.1
true
io.github.swagger2markup
swagger2markup-maven-plugin
${swagger2markup.plugin.version}
io.github.swagger2markup
swagger2markup-import-files-ext
${swagger2markup.extension.version}
io.github.swagger2markup
swagger2markup
${swagger2markup.version}
${swagger.input}
${generated.asciidoc.directory}
ASCIIDOC
TAGS
${project.basedir}/src/docs/asciidoc/extensions/overview
${project.basedir}/src/docs/asciidoc/extensions/definitions
${project.basedir}/src/docs/asciidoc/extensions/paths
${project.basedir}src/docs/asciidoc/extensions/security
generate-sources
convertSwagger2markup
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
org.asciidoctor
asciidoctorj-pdf
${asciidoctorj.pdf.version}
org.jruby
jruby-complete
${jruby.version}
org.asciidoctor
asciidoctorj
${asciidoctorj.version}
${asciidoctor.input.directory}
index.adoc
book
left
3
${generated.asciidoc.directory}
output-html
test
process-asciidoc
html5
${asciidoctor.html.output.directory}
output-pdf
test
process-asciidoc
pdf
${asciidoctor.pdf.output.directory}
文档生成代码(我这里是直接使用swagger.json 转成pdf 、html2)
package com.tanzj.test;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerStaticTest {
@Autowired
private WebApplicationContext context;
private String snippetDir = "target/generated-snippets";
private String outputDir = "target/asciidoc";
private MockMvc mockMvc;
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();
}
@Test
public void Test() throws Exception {
// mockMvc.perform(get("http://192.168.10.165:8080/v2/api-docs").accept(MediaType.APPLICATION_JSON))
// .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
// .andExpect(status().isOk())
// .andReturn();
Swagger2MarkupConverter.from(outputDir + "/swagger.json")
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withExamples(snippetDir)
.build()
.intoFolder(outputDir);
}
}
新建src/docs/asciidoc/index.adoc
include::{generated}/overview.adoc[]
include::manual_content1.adoc[]
include::manual_content2.adoc[]
include::{generated}/security.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]新建src/docs/asciidoc/manual_content1.adoc 这里面的内容可以自己编写（类似于文档说明）
== Chapter of manual content 1
This is some dummy text
=== Sub chapter
Dummy text of sub chapter
新建src/docs/asciidoc/manual_content2.adoc 这里面的内容可以自己编写（类似于文档说明）
== Chapter of manual content 2
This is some dummy text
新建src/swagger/swagger.json 就是将swagger.json 的内容转成pdf
获取的路径
{
"swagger": "2.0",
"info": {
"description": "测试环境访问： http://www.tanzj_test.com/ 生产环境访问： http://www.tanzj_prod.com/",
"version": "1.0",
"title": "Swagger api 文档 demo",
"termsOfService": "http://www.tanzj.com/"
},
"host": "localhost:8080",
"basePath": "/",
"tags": [
{
"name": "demo-controller",
"description": "demo管理"
}
],
"paths": {
"/demo/getDemo": {
"get": {
"tags": [
"demo-controller"
],
"summary": "getDemo",
"description": "查询demo",
"operationId": "getDemoUsingGET",
"produces": [
"*/*"
],
"parameters": [
{
"name": "accessToken",
"in": "header",
"description": "登录令牌",
"required": false,
"type": "string"
},
{
"name": "demoId",
"in": "query",
"description": "demo id",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/demo对象返回"
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"401": {
"description": "无访问权限",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "地址不存在",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"500": {
"description": "服务器内部错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
}
}
}
},
"/demo/listDemo": {
"post": {
"tags": [
"demo-controller"
],
"summary": "listDemo",
"description": "查询demo",
"operationId": "listDemoUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "test1.name",
"in": "query",
"description": "名称",
"required": false,
"type": "string"
},
{
"name": "test1.description",
"in": "query",
"description": "描述",
"required": false,
"type": "string"
},
{
"name": "test2.name",
"in": "query",
"description": "名称",
"required": false,
"type": "string"
},
{
"name": "test2.description",
"in": "query",
"description": "描述",
"required": false,
"type": "string"
},
{
"name": "accessToken",
"in": "header",
"description": "登录令牌",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/demo分页信息"
}
},
"201": {
"description": "Created"
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"401": {
"description": "无访问权限",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "地址不存在",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"500": {
"description": "服务器内部错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
}
}
}
},
"/demo/listDemo1": {
"post": {
"tags": [
"demo-controller"
],
"summary": "listDemo1",
"description": "查询demo1",
"operationId": "listDemo1UsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "name",
"in": "query",
"description": "名称",
"required": false,
"type": "string"
},
{
"name": "description",
"in": "query",
"description": "描述",
"required": false,
"type": "string"
},
{
"name": "accessToken",
"in": "header",
"description": "登录令牌",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/demo分页信息"
}
},
"201": {
"description": "Created"
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"401": {
"description": "无访问权限",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "地址不存在",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
},
"500": {
"description": "服务器内部错误",
"schema": {
"$ref": "#/definitions/api接口通用返回对象"
}
}
}
}
}
},
"definitions": {
"PageUtil«demo对象信息»": {
"type": "object",
"properties": {
"currentPage": {
"type": "integer",
"format": "int32"
},
"list": {
"type": "array",
"items": {
"$ref": "#/definitions/demo对象信息"
}
},
"pageSize": {
"type": "integer",
"format": "int32"
},
"totalCount": {
"type": "integer",
"format": "int64"
},
"totalPage": {
"type": "integer",
"format": "int32"
}
},
"title": "PageUtil«demo对象信息»"
},
"api接口通用返回对象": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"description": "返回码",
"allowEmptyValue": false
},
"msg": {
"type": "string",
"description": "错误信息",
"allowEmptyValue": false
},
"version": {
"type": "string",
"description": "api版本",
"allowEmptyValue": false
}
},
"title": "api接口通用返回对象"
},
"demo分页信息": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"description": "返回码",
"allowEmptyValue": false
},
"msg": {
"type": "string",
"description": "错误信息",
"allowEmptyValue": false
},
"result": {
"description": "数据列表",
"allowEmptyValue": false,
"$ref": "#/definitions/PageUtil«demo对象信息»"
},
"version": {
"type": "string",
"description": "api版本",
"allowEmptyValue": false
}
},
"title": "demo分页信息"
},
"demo对象信息": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "地址",
"allowEmptyValue": false
},
"createTime": {
"type": "string",
"format": "date-time",
"description": "创建时间",
"allowEmptyValue": false
},
"description": {
"type": "string",
"description": "描述",
"allowEmptyValue": false
},
"id": {
"type": "integer",
"format": "int32",
"description": "demo id",
"allowEmptyValue": false
},
"name": {
"type": "string",
"description": "名称",
"allowEmptyValue": false
}
},
"title": "demo对象信息"
},
"demo对象返回": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"description": "返回码",
"allowEmptyValue": false
},
"msg": {
"type": "string",
"description": "错误信息",
"allowEmptyValue": false
},
"result": {
"description": "demo信息",
"allowEmptyValue": false,
"$ref": "#/definitions/demo对象信息"
},
"version": {
"type": "string",
"description": "api版本",
"allowEmptyValue": false
}
},
"title": "demo对象返回"
}
}
}然后使用maven插件生成文档
执行
mvn clean test -Dtest=SwaggerStaticDocTest -DfailIfNoTests=false
使用idea 请执行
clean test -Dtest=SwaggerStaticDocTest -DfailIfNoTests=false
idea执行方式
运行即可
