目录
Swagger文章汇总
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
项目版本说明：
- spring boot 2.0.x
- swagger 2.8.0
swagger2markup代码方式
第一步：编辑pom.xml增加需要使用的相关依赖和仓库
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>其中依赖组件，这两个要注意，在离线开发环境，需要自己手动添加到本地仓库
<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.0</version>
<scope>compile</scope>
</dependency>第二步：编写一个单元测试用例来生成执行生成文档的代码
生成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
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插件
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.3</version>
<configuration>
<swaggerInput>http://localhost:9210/v2/api-docs</swaggerInput>
<!-- 生成asciidoc格式 -->
<outputFile>src/docs/asciidoc/generated/all</outputFile>
<!-- <outputDir>src/docs/asciidoc/generated</outputDir>-->
<!-- 生成markdown格式 -->
<!-- <outputFile>src/docs/markdown/generated/all</outputFile>-->
<config>
<!-- 生成asciidoc格式 -->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!-- 生成markdown格式 -->
<!-- <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
<swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
<swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
<swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
</plugin>
生成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
生成HTML文档
添加asciidoctor插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html5</backend>
<attributes>
<!--导航栏在左-->
<toc>left</toc>
<!--显示层级数-->
<toclevels>3</toclevels>
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
生成HTML文档
- 生成asciidoc文档
- 执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
相关说明
- sourceDirectory：asciidoc文档所在目录
- outputDirectory：HTML的输出目录
- backend：类型
生成PDF文档
添加asciidoctor插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
<backend>pdf</backend>
</configuration>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
</plugin>
生成PDF文档
- 生成asciidoc文档
- 执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
解决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文档
添加插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
</configuration>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<attributes>
<!--导航栏在左-->
<toc>left</toc>
<!--显示层级数-->
<toclevels>3</toclevels>
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
同时生成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/
