目录
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
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插件
<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
生成asciidoc或markdown文档
生成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：类型
生成HTML文档
生成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出现乱码、空白的问题：
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/
