本文默认文档处理目录为 /src/doc , 可以根据自己喜好自行配置
一、 生成流程
- 由 swagger.json 生成 Asciidoc 文档 (swagger2Markup)
- 由 Asciidoc 文档生成PDF格式的文档 (asciidoctor-maven-plugin)
二、生成 Asciidoc
swagger.json 获取路径如下图:
可以以API 和插件两种方式,将swagger.json 转换为asciidoc文档
2.1 Swagger2Markup Api 生成
需要添加依赖:
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</dependency>
package com.example
import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Path;
import java.nio.file.Paths;
import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
public class AsciidocConverter {
public static void main(String... args) throws MalformedURLException {
// 用于转换的swagger.json可以来自于本地文件,也可以来http 获取
// Path localSwaggerFile = Paths.get("/path/to/swagger.json");
URL remoteSwaggerFile = new URL("http://60.60.60.74:18041/v2/api-docs");
// asciidoc 输出文件夹
Path outputDir = Paths.get("./src/doc/asciidoc/generated");
// 转换配置设置
// 配置书写方式有多种,可参考 Swagger2MarkupConfigBuilder 构造函数
// 此处可配置输出格式为 markdown 文档
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
.withConfig(config)
.build()
.toFolder(outputDir);
}
}
常用属性配置表,完整属性参考:官方文档
项目 | Value | 允许值 | 默认值 |
---|---|---|---|
swagger2markup.markupLanguage | 生成文件类型 | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | ASCIIDOC |
swagger2markup.swaggerMarkupLanguage | swagger 描述所用语言 | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | MARKDOWN |
swagger2markup.pathsGroupedBy | API 分组方法 | AS_IS, TAGS, REGEX | AS_IS |
swagger2markup.outputLanguage | 标签语言 | EN, DE, FR, RU | EN |
swagger2markup.lineSeparator | line separator which should be used | UNIX, WINDOWS, MAC | System-dependent |
swagger2markup.generatedExamplesEnabled | 是否生成example | true, false | false |
swagger2markup.flatBodyEnabled | 是否区分body 参数和其他参数 | true, false | false |
swagger2markup.pathSecuritySectionEnabled | 是否禁用路径的安全部分 | true ,false | true |
swagger2markup.basePathPrefixEnabled | 是否给所有路径添加前缀 | true , false | false |
2.2 swagger2markup 插件生成 asciidoc
pom.xml 添加插件
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.3</version>
<dependencies>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</dependency>
</dependencies>
<configuration>
<!--本地 swagger.json 路径 或 远程访问地址-->
<swaggerInput>http://60.60.60.74:18041/v2/api-docs</swaggerInput>
<!-- 输出目录 -->
<outputDir>./src/doc/asciidoc/generated</outputDir>
<config>
<!--设置输出文件的语言:ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!--设置目录的展现方式-->
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>convertSwagger2markup</goal>
</goals>
</execution>
</executions>
</plugin>
插件配置相关参数,参考上一小节属性表格
2.3 输出结果
三、ASCIIDOC => PDF、HTML
采用 asciidoctor-maven-plugin插件的方式来转化Ascii文档。
3.1 添加中文主题和字体文件夹
下载字体(RobotoMono 开头和 KaiGenGothicCN 开头的字体文件)和theme文件(Source code (zip))。
字体下载链接:https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
然后在项目的文档目录下创建fonts和themes两个目录,把下载的8个字体文件复制到fonts目录下,解压asciidoctor-pdf-cjk-kai_gen_gothic-0.1.0-fonts.zip文件,把data\themes\下的cn-theme.yml复制到themes目录下
3.2 手写index.adoc
此文件主要用于指引插件访问asciidoc文档。
3.3 配置插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<!-- Include Asciidoctor PDF for pdf generation -->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
<!-- Comment this section to use the default jruby artifact provided by the plugin -->
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>9.1.8.0</version>
</dependency>
<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>1.5.4</version>
</dependency>
</dependencies>
<!-- Configure generic document generation settings -->
<configuration>
<!--默认指向 ${basedir}/src/main/asciidoc-->
<sourceDirectory>./src/doc/</sourceDirectory>
<!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run
separate executions for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>./src/doc/asciidoc/html</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>./src/doc/asciidoc/pdf</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<doctype>book</doctype>
<attributes>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<pdf-fontsdir>./fonts</pdf-fontsdir>
<pdf-stylesdir>./themes</pdf-stylesdir>
<pdf-style>cn</pdf-style>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
四、备注
- 代码示例中的各处访问路径均为本人项目配置路径,可自行配置。
- 可自行设置文档生成的时间,修改此处即可:<phase>package</phase>