swagger API导出为HTML或者PDF

现在有很多项目都是使用的swagger，将API直接写在swagger文档中，使用起来非常方便，并且支持在线调试。但是它不方便对外提供，这里我们找到了一种方法，可以方便的将swagger API导出为HTML或者PDF。

主要使用maven的两个插件：1. swagger2markup-maven-plugin2. asciidoctor-maven-plugin

下面我们会详细讲解怎么使用他们和可能会遇到的问题。

什么是Asciidoc

AsciiDoc是一种文本文档格式，用于编写笔记，文档，文章，书籍，电子书，幻灯片，网页，手册页和博客。 AsciiDoc文件可以转换为多种格式，包括HTML，PDF，EPUB，手册页。

AsciiDoc是高度可配置的：AsciiDoc源文件语法和后端输出标记（可以是几乎任何类型的SGML / XML标记）都可以由用户自定义和扩展。

AsciiDoc是免费软件，并根据GNU通用公共许可证版本2（GPLv2）的条款获得许可。

AsciiDoc，它的设计初衷就是为了解决写书规模的问题，并且是 O’Reilly 的在线出版平台 Atlas 的推荐语言。

swagger2markup-maven-plugin

swagger2markup-maven-plugin这个插件可以将swagger的API转换为ASCIIDOC或者MARKDOWN和CONFLUENCE_MARKUP。这里我们选择转换为ASCIIDOC。

在build中加入如下代码：

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.7</version>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>http://localhost:7667/v2/api-docs</swaggerInput>
                    <outputDir>target/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

版本我们用的是最新的1.3.7.

target/docs/asciidoc/generated 是生成的ASCIIDOC的目标地址，我们会在后面将其转换为HTML或者PDF。

运行下面命令生成asciidoc：

mvn swagger2markup:convertSwagger2markup 

asciidoctor-maven-plugin

有了asciidoc，我们使用asciidoctor-maven-plugin将其转换为HTML和PDF。

Asciidoctor是一种快速，开放源代码的文本处理器和发布工具链，用于将AsciiDoc内容转换为HTML5，DocBook，PDF和其他格式。 Asciidoctor用Ruby编写，可在所有主要操作系统上运行。

Asciidoctor提供了一个asciidoctor-maven-plugin，可以方便的在maven环境使用。其配置如下：

        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>2.0.0-RC.1</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.18</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.2.7.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>2.0.0</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <!-- Attributes common to all output formats -->
                    <attributes>
                        <sourcedir>target/docs/asciidoc/generated</sourcedir>
                    </attributes>
                </configuration>
                <executions>
                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <!-- Since 1.5.0-alpha.9 PDF back-end can use 'rouge' as well as 'coderay'
                            for source highlighting -->
                            <!-- Due to a known issue on windows, it is recommended to use 'coderay' until an new version of 'rouge' is released.
                            -->
                            <sourceHighlighter>coderay</sourceHighlighter>
                            <attributes>
                                <icons>font</icons>
                                <pagenums/>
                                <toc/>
                                <idprefix/>
                                <idseparator>-</idseparator>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

运行下面命令生成HTML和PDF：

mvn generate-resources

使用命令行

上面讲到了，Asciidoctor是基于ruby的，有了asciidoc之后，我们也可以直接使用Asciidoctor的命令行来进行转换。步骤如下：

1. 安装rvm：rvm是一个ruby的版本管理工具，方便使用。当然你也可以使用系统原生的ruby。ruby的版本必须在2.3以上。
2. 安装asciidoctor-pdf：gem install asciidoctor-pdf --pre
3. 转换pdf：asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc

PDF的中文展示

Asciidoctor可以处理全范围的UTF-8字符的字符集。这意味着你可以写你的文档中的任何语言，使用UTF-8编码的文件，并期望Asciidoctor到文本正确转换。但是，您可能会注意到PDF中缺少某些语言的某些字符，例如中文。

如果您使用非拉丁语书写，则需要使用专门的主题来提供必要的字体。例如，以从写在CJK语言文档的PDF如中国，你需要使用一个CJK主题。您可以通过安装asciidoctor-pdf-cjk-kai_gen_gothic gem获得这样的主题。

采用专用的主题，是因为PDF需要你自己提供字体来为所有字符提供字形。没有一种字体可以支持世界上所有的语言（尽管像Noto Serif之类的语言肯定会比较接近）。

因此，我们采取的策略是针对每个语言家族（例如CJK）创建单独的专用主题。当然，您可以自由地遵循这种模式，并使用选择的字体来创建自己的主题。

怎么创建主题这里就不详细讲解了，有兴趣的小伙伴可以自行查阅有关资料。

如何安装：

gem install asciidoctor-pdf-cjk-kai_gen_gothic

下载字体：asciidoctor-pdf-cjk-kai_gen_gothic-install

这个主题支持以下几种字体：

• KaiGenGothicCN
• KaiGenGothicJP
• KaiGenGothicKR
• KaiGenGothicTW

使用下面的命令来转换PDF：

asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=THEME doc.asc

这里我遇到了一个问题，如果字体选择KaiGenGothicCN， 那么会在运行时候报错：

undefined method `strip_extended' for nil:NilClass
  Use --trace for backtrace

详细查看–trace，会发现报错的是ttfunk/table/name.rb：

@postscript_name = @strings[6].first.strip_extended

从字体中获取到的@strings[6]是空。 那么怎么办呢？

很简单，使用KaiGenGothicTW字体即可。

PDF中文主题在maven中的使用

那么有了命令行，我们怎么在maven中使用呢？

请使用如下的XML配置：

<execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>target/docs/asciidoc/pdf</outputDirectory>
                            <attributes>
                                <pdf-stylesdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/themes</pdf-stylesdir>
                                <pdf-style>KaiGenGothicTW</pdf-style>
                                <pdf-fontsdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts</pdf-fontsdir>
                                <icons>font</icons>
                                <pagenums/>
                                <toc/>
                                <idprefix/>
                                <idseparator>-</idseparator>
                            </attributes>
                        </configuration>
                    </execution>

请关注如下几个字段：

pdf-stylesdir：你安装的中文主题的目录pdf-style：中文主题的名称pdf-fontsdir： 中文主题字体的名称。

好了，本文讲到这里，有疑问的小伙伴可以发邮件或者留言提问。谢谢。

更多教程请参考 flydean的博客

.asciidoctor-pdf的安装

1.gem install asciidoctor-pdf 报gem指令不存在？

2.gem 指令 是基于ruby的 所以先安装ruby 参考ruby的安装 安装完成后 执行1指令

https://www.runoob.com/ruby/ruby-installation-windows.html

3.ruby安装包在目录中

4.asciidoctor-pdf index.adoc adoc文件目录 针对index.adon文件执行转pdf指令 生成同名文件index.pdf

2.出现中文乱码的问题

1.将asciidoctor-pdf/data/fonts,复制到当前项目目录，并将某个中文字体复制到fonts文件夹中

2.将asciidoctor-pdf安装目录中default-theme.yml，复制到当前项目目录下，并改名为theme.yml

3.将theme.yml中的mplus1p开头的文件名，换成1中找的中文字体

4.执行命令行 asciidoctor-pdf -a pdf-style=theme.yml -a pdf-fontsdir=fonts index.adoc

原理：将数字转成ASCII码对应的十进制

JavaScript API

String.fromCharCode(number)

示例

let ch1 = [];   //存储大写字母
let ch2 = [];   //存储小写字母

for(let i=0; i<26; i++) {
  ch1.push(String.fromCharCode(i+65));//大写

  ch2.push(String.fromCharCode(i + 97));//小写
}

console.log(ch1);
console.log(ch2);

拓展：ASCII

什么是ASCII？

ASCII（American Standard Code for Information Interchange， 美国标准信息交换代码）是基于拉丁字母的一套电脑编码系统，主要用于显示现代英语和其他西欧语言。它是现今最通用的单字节编码系统，并等同于国际标准ISO/IEC 646。

ASCII 产生原因

在计算机中，所有的数据在存储和运算时都要使用二进制数表示（因为计算机用高电平和低电平分别表示1和0），例如，像a、b、c、d这样的52个字母（包括大写）以及0、1等数字还有一些常用的符号（例如*、#、@等）在计算机中存储时也要使用二进制数来表示，而具体用哪些二进制数字表示哪个符号，当然每个人都可以约定自己的一套（这就叫编码），而大家如果要想互相通信而不造成混乱，那么大家就必须使用相同的编码规则，于是美国有关的标准化组织就出台了ASCII编码，统一规定了上述常用符号用哪些二进制数来表示。

美国信息交换标准代码是由美国国家标准学会(American National Standard Institute , ANSI )制定的，是一种标准的单字节字符编码方案，用于基于文本的数据。它最初是美国国家标准，供不同计算机在相互通信时用作共同遵守的西文字符编码标准，后来它被国际标准化组织（International Organization for Standardization, ISO）定为国际标准，称为ISO 646标准。适用于所有拉丁文字字母 。

ASCII 大小规则

常见ASCII码的大小规则：0~9<A~Z<a~z。

1. 数字比字母要小。如 “7”<“F”；
2. 数字0比数字9要小，并按0到9顺序递增。如 “3”<“8” ；
3. 字母A比字母Z要小，并按A到Z顺序递增。如“A”<“Z” ；
4. 同个字母的大写字母比小写字母要小32。如“A”<“a” 。

几个常见字母的ASCII码大小： “A”为65；“a”为97；“0”为 48。

ASCII 存在的问题

在英语中，用128个符号编码便可以表示所有，但是用来表示其他语言，128个符号是不够的。比如，在法语中，字母上方有注音符号，它就无法用 ASCII 码表示。于是，一些欧洲国家就决定，利用字节中闲置的最高位编入新的符号。比如，法语中的é的编码为130（二进制10000010）。这样一来，这些欧洲国家使用的编码体系，可以表示最多256个符号。

但是，这里又出现了新的问题。不同的国家有不同的字母，因此，哪怕它们都使用256个符号的编码方式，代表的字母却不一样。比如，130在法语编码中代表了é，在希伯来语编码中却代表了字母Gimel (ג)，在俄语编码中又会代表另一个符号。但是不管怎样，所有这些编码方式中，0--127表示的符号是一样的，不一样的只是128--255的这一段 。

至于亚洲国家的文字，使用的符号就更多了，汉字就多达10万左右。一个字节只能表示256种符号，肯定是不够的，就必须使用多个字节表达一个符号。比如，简体中文常见的编码方式是 GB2312，使用两个字节表示一个汉字，所以理论上最多可以表示 256 x 256 = 65536 个符号。

ASCII 标准表

ASCII码表具体如下所示：