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，它的設計初衷就是為了解決寫書規(guī)模的問題，并且是 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是一種快速，開放源代碼的文本處理器和發(fā)布工具鏈，用于將AsciiDoc內容轉換為HTML5，DocBook，PDF和其他格式。 Asciidoctor用Ruby編寫，可在所有主要操作系統上運行。

Asciidoctor提供了一個asciidoctor-maven-plugin，可以方便的在maven環(huán)境使用。其配置如下：

        <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）創(chuàng)建單獨的專用主題。當然，您可以自由地遵循這種模式，并使用選擇的字體來創(chuàng)建自己的主題。

怎么創(chuàng)建主題這里就不詳細講解了，有興趣的小伙伴可以自行查閱有關資料。

如何安裝：

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，會發(fā)現報錯的是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： 中文主題字體的名稱。

好了，本文講到這里，有疑問的小伙伴可以發(fā)郵件或者留言提問。謝謝。

更多教程請參考 flydean的博客

.asciidoctor-pdf的安裝

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

2.gem 指令 是基于ruby的 所以先安裝ruby 參考ruby的安裝 安裝完成后 執(zhí)行1指令

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

3.ruby安裝包在目錄中

4.asciidoctor-pdf index.adoc adoc文件目錄 針對index.adon文件執(zhí)行轉pdf指令 生成同名文件index.pdf

2.出現中文亂碼的問題

1.將asciidoctor-pdf/data/fonts,復制到當前項目目錄，并將某個中文字體復制到fonts文件夾中

2.將asciidoctor-pdf安裝目錄中default-theme.yml，復制到當前項目目錄下，并改名為theme.yml

3.將theme.yml中的mplus1p開頭的文件名，換成1中找的中文字體

4.執(zhí)行命令行 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， 美國標準信息交換代碼）是基于拉丁字母的一套電腦編碼系統，主要用于顯示現代英語和其他西歐語言。它是現今最通用的單字節(jié)編碼系統，并等同于國際標準ISO/IEC 646。

ASCII 產生原因

在計算機中，所有的數據在存儲和運算時都要使用二進制數表示（因為計算機用高電平和低電平分別表示1和0），例如，像a、b、c、d這樣的52個字母（包括大寫）以及0、1等數字還有一些常用的符號（例如*、#、@等）在計算機中存儲時也要使用二進制數來表示，而具體用哪些二進制數字表示哪個符號，當然每個人都可以約定自己的一套（這就叫編碼），而大家如果要想互相通信而不造成混亂，那么大家就必須使用相同的編碼規(guī)則，于是美國有關的標準化組織就出臺了ASCII編碼，統一規(guī)定了上述常用符號用哪些二進制數來表示。

美國信息交換標準代碼是由美國國家標準學會(American National Standard Institute , ANSI )制定的，是一種標準的單字節(jié)字符編碼方案，用于基于文本的數據。它最初是美國國家標準，供不同計算機在相互通信時用作共同遵守的西文字符編碼標準，后來它被國際標準化組織（International Organization for Standardization, ISO）定為國際標準，稱為ISO 646標準。適用于所有拉丁文字字母 。

ASCII 大小規(guī)則

常見ASCII碼的大小規(guī)則：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 碼表示。于是，一些歐洲國家就決定，利用字節(jié)中閑置的最高位編入新的符號。比如，法語中的é的編碼為130（二進制10000010）。這樣一來，這些歐洲國家使用的編碼體系，可以表示最多256個符號。

但是，這里又出現了新的問題。不同的國家有不同的字母，因此，哪怕它們都使用256個符號的編碼方式，代表的字母卻不一樣。比如，130在法語編碼中代表了é，在希伯來語編碼中卻代表了字母Gimel (?)，在俄語編碼中又會代表另一個符號。但是不管怎樣，所有這些編碼方式中，0--127表示的符號是一樣的，不一樣的只是128--255的這一段 。

至于亞洲國家的文字，使用的符號就更多了，漢字就多達10萬左右。一個字節(jié)只能表示256種符號，肯定是不夠的，就必須使用多個字節(jié)表達一個符號。比如，簡體中文常見的編碼方式是 GB2312，使用兩個字節(jié)表示一個漢字，所以理論上最多可以表示 256 x 256 = 65536 個符號。

ASCII 標準表

ASCII碼表具體如下所示：