Swagger2离线文档：swagger2markup代码和插件方式
目录
Swagger文章汇总
Swagger2Markup简介
项目版本说明：
swagger2markup代码方式
第一步：编辑pom.xml增加需要使用的相关依赖和仓库
第二步：编写一个单元测试用例来生成执行生成文档的代码
生成AsciiDoc
生成markdown
生成confluence
swagger2markup插件方式
生成asciidoc或markdown文档
添加swagger2markup插件
生成asciidoc或markdown文档
相关说明
生成HTML文档
添加asciidoctor插件
生成HTML文档
生成PDF文档
添加asciidoctor插件
生成PDF文档
解决PDF出现乱码、空白的问题：
同时生成HTML与PDF文档
添加插件
同时生成HTML与PDF文档
Swagger文章汇总
- SpringBoot集成Swagger2，以及Swagger2常用API
- Swagger2离线文档：PDF和Html5格式
- SpringBoot整合Shiro，Swagger2页面样式加载不出来问题
- Swagger2离线文档：swagger2markup代码和插件方式
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
项目主页：https://github.com/Swagger2Markup/swagger2markup
项目版本说明：
- spring boot 2.0.x
- swagger 2.8.0
swagger2markup代码方式
第一步：编辑pom.xml增加需要使用的相关依赖和仓库
io.github.swagger2markup
swagger2markup
1.3.1
其中依赖组件，这两个要注意，在离线开发环境，需要自己手动添加到本地仓库
nl.jworks.markdown_to_asciidoc
markdown_to_asciidoc
1.0
compile
nl.jworks.markdown_to_asciidoc
markdown_to_asciidoc
1.0
compile
第二步：编写一个单元测试用例来生成执行生成文档的代码
生成AsciiDoc
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
@Test
public void generateAsciiDocs() throws Exception {
// 输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/asciidoc/generated"));
}
}- 通过Java代码来生成：只需要修改
withMarkupLanguage属性来指定不同的格式以及toFolder属性为结果指定不同的输出目录。
生成markdown
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/markdown/generated"));生成confluence
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/confluence/generated"));以上代码内容很简单，大致说明几个关键内容：
MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUPfrom(new URL("http://localhost:8080/v2/api-docs")：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式toFolder(Paths.get("src/docs/asciidoc/generated")：指定最终生成文件的具体目录位置
在执行了上面的测试用例之后，我们就能在当前项目的src目录下获得如下内容：
AsciiDoc
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
AsciiDoc
Markdown和Confluence
src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md可以看到，这种方式在运行之后就生成出了4个不同的静态文件。
输出到单个文件
如果不想分割结果文件，也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")为toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。
swagger2markup插件方式
生成asciidoc或markdown文档
添加swagger2markup插件
io.github.swagger2markup
swagger2markup-maven-plugin
1.3.3
http://localhost:9210/v2/api-docs
src/docs/asciidoc/generated/all
ASCIIDOC
ZH
true
false
TAGS
生成asciidoc或markdown文档
- 运行项目
- 执行swagger2markup插件：maven窗口：指定项目下的Plugins.swagger2markup
相关说明
- swaggerInput：swagger生成的接口json数据文件。
- 输出：
- outputFile：输出到单一文件中
- outputDir：输出到指定文件中
- swagger2markup.markupLanguage：输出格式
- swagger2markup.outputLanguage：语言类型：如中文（ZH），默认英语（EN）
- swagger2markup.generatedExamplesEnabled：指定是否应该生成HTTP请求和响应示例，默认false
- swagger2markup.inlineSchemaEnabled：是否启用参数内联
- swagger2markup.pathsGroupedBy：api排序规则 一般用tags排序
swagger2markup插件配置说明
http://swagger2markup.github.io/swagger2markup/1.3.3/#_swagger2markup_properties
生成asciidoc或markdown文档
生成HTML文档
添加asciidoctor插件
org.asciidoctor
asciidoctor-maven-plugin
1.5.6
src/docs/asciidoc/generated
src/docs/asciidoc/html
html5
left
3
true
生成HTML文档
- 生成asciidoc文档
- 执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
相关说明
- sourceDirectory：asciidoc文档所在目录
- outputDirectory：HTML的输出目录
- backend：类型
生成HTML文档
生成PDF文档
添加asciidoctor插件
org.asciidoctor
asciidoctor-maven-plugin
1.5.6
src/docs/asciidoc/generated
src/docs/asciidoc/pdf
pdf
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.16
生成PDF文档
- 生成asciidoc文档
- 执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
解决PDF出现乱码、空白的问题：
PDF出现乱码、空白的问题
-
maven仓库中的asciidoctorj-pdf jar包，使用压缩工具打开：
- 进入asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\ 目录
- fonts：字体文件目录
- themes：配置文件目录
-
下载字体：
- 字体下载：https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
- 注：只需下载KaiGenGothicCN-Bold.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf 即可
- 将字体文件放入fonts目录中
-
修改配置
- 进入themes目录，修改default-theme.yml文件
- 修改以base:font_family属性值对应的字体文件配置：在font:catalog下。
base: font_family: Noto Serif font: catalog: Noto Serif: normal: KaiGenGothicCN-Regular.ttf bold: KaiGenGothicCN-Bold.ttf italic: KaiGenGothicCN-Regular-Italic.ttf bold_italic: KaiGenGothicCN-Bold-Italic.ttf
同时生成HTML与PDF文档
添加插件
org.asciidoctor
asciidoctor-maven-plugin
1.5.6
src/docs/asciidoc/generated
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.16
output-html
generate-resources
process-asciidoc
html5
src/docs/asciidoc/html
left
3
true
output-pdf
generate-resources
process-asciidoc
pdf
src/docs/asciidoc/pdf
同时生成HTML与PDF文档
- 生成asciidoc文档
- 执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
- 生成文档（二者选其一）：注：此步骤耗时，大概七八分钟
- 执行命令mvn generate-resources
- 使用idea设置快捷启动：run/debug configurations -> maven -> command line:generate-resources，执行
PDFPDF出现乱码、空白的问题
- 参考单独生成PDF问题解决
相关说明
- executions：多个执行任务配置
- execution.id：不可重复
- 其他：参考单独生成HTML与PDF相关说明
参考链接：
http://blog.didispace.com/swagger2markup-markdown-confluence/