文章目錄

• • 將swagger API導出為HTML或者PDF
  • 什么是Asciidoc
  • swagger2markup-maven-plugin
  • asciidoctor-maven-plugin
  • 使用命令行
  • PDF的中文展示
  • PDF中文主題在maven中的使用

將swagger API導出為HTML或者PDF

現在有很多項目都是使用的swagger，將API直接寫在swagger文檔中，使用起來非常方便，并且支持在線調試。但是它不方便對外提供，這里我們找到了一種方法，可以方便的將swagger API導出為HTML或者PDF。

主要使用maven的兩個插件：

swagger2markup-maven-plugin

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的命令行來進行轉換。步驟如下：

安裝rvm：rvm是一個ruby的版本管理工具，方便使用。當然你也可以使用系統原生的ruby。ruby的版本必須在2.3以上。

安裝asciidoctor-pdf：

gem install asciidoctor-pdf --pre

轉換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:NilClassUse --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的博客

總結

以上是生活随笔為你收集整理的怎么将swagger API导出为HTML或者PDF的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。