Swagger2Markup 生成PDF、HTML格式的API文档方法整理（中文支持）


本文默认文档处理目录为 /src/doc , 可以根据自己喜好自行配置

一、 生成流程

  1. 由 swagger.json 生成 Asciidoc 文档 （swagger2Markup）
  2. 由 Asciidoc 文档生成PDF格式的文档 （asciidoctor-maven-plugin）

二、生成 Asciidoc

swagger.json 获取路径如下图：
在这里插入图片描述
可以以API 和插件两种方式，将swagger.json 转换为asciidoc文档

2.1 Swagger2Markup Api 生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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 添加插件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<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 配置插件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
<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>

四、备注

  • 代码示例中的各处访问路径均为本人项目配置路径，可自行配置。
  • 可自行设置文档生成的时间，修改此处即可：package

五、参考

  • https://blog.csdn.net/lihuaijun/article/details/79727863
  • http://swagger2markup.github.io/swagger2markup/1.3.3/
  • https://github.com/asciidoctor/asciidoctor-maven-plugin
  • https://github.com/Swagger2Markup/swagger2markup-maven-project-template