現在有很多項目都是使用的swagger,將API直接寫在swagger文檔中,使用起來非常方便,并且支持在線調試。但是它不方便對外提供,這里我們找到了一種方法,可以方便的將swagger API導出為HTML或者PDF。
主要使用maven的兩個插件:1. swagger2markup-maven-plugin2. asciidoctor-maven-plugin
下面我們會詳細講解怎么使用他們和可能會遇到的問題。
AsciiDoc是一種文本文檔格式,用于編寫筆記,文檔,文章,書籍,電子書,幻燈片,網頁,手冊頁和博客。 AsciiDoc文件可以轉換為多種格式,包括HTML,PDF,EPUB,手冊頁。
AsciiDoc是高度可配置的:AsciiDoc源文件語法和后端輸出標記(可以是幾乎任何類型的SGML / XML標記)都可以由用戶自定義和擴展。
AsciiDoc是免費軟件,并根據GNU通用公共許可證版本2(GPLv2)的條款獲得許可。
AsciiDoc,它的設計初衷就是為了解決寫書規(guī)模的問題,并且是 O’Reilly 的在線出版平臺 Atlas 的推薦語言。
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
有了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的命令行來進行轉換。步驟如下:
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
這個主題支持以下幾種字體:
使用下面的命令來轉換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字體即可。
那么有了命令行,我們怎么在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
avaScript
原理:將數字轉成ASCII碼對應的十進制
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(American Standard Code for Information Interchange, 美國標準信息交換代碼)是基于拉丁字母的一套電腦編碼系統,主要用于顯示現代英語和其他西歐語言。它是現今最通用的單字節(jié)編碼系統,并等同于國際標準ISO/IEC 646。
在計算機中,所有的數據在存儲和運算時都要使用二進制數表示(因為計算機用高電平和低電平分別表示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ī)則:0~9<A~Z<a~z。
幾個常見字母的ASCII碼大?。?“A”為65;“a”為97;“0”為 48。
在英語中,用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碼表具體如下所示:
Bin (二進制) | Oct (八進制) | Dec (十進制) | Hex (十六進制) | 縮寫/字符 | 解釋 |
0000 0000 | 00 | 0 | 0x00 | NUL(null) | 空字符 |
0000 0001 | 01 | 1 | 0x01 | SOH(start of headline) | 標題開始 |
0000 0010 | 02 | 2 | 0x02 | STX (start of text) | 正文開始 |
0000 0011 | 03 | 3 | 0x03 | ETX (end of text) | 正文結束 |
0000 0100 | 04 | 4 | 0x04 | EOT (end of transmission) | 傳輸結束 |
0000 0101 | 05 | 5 | 0x05 | ENQ (enquiry) | 請求 |
0000 0110 | 06 | 6 | 0x06 | ACK (acknowledge) | 收到通知 |
0000 0111 | 07 | 7 | 0x07 | BEL (bell) | 響鈴 |
0000 1000 | 010 | 8 | 0x08 | BS (backspace) | 退格 |
0000 1001 | 011 | 9 | 0x09 | HT (horizontal tab) | 水平制表符 |
0000 1010 | 012 | 10 | 0x0A | LF (NL line feed, new line) | 換行鍵 |
0000 1011 | 013 | 11 | 0x0B | VT (vertical tab) | 垂直制表符 |
0000 1100 | 014 | 12 | 0x0C | FF (NP form feed, new page) | 換頁鍵 |
0000 1101 | 015 | 13 | 0x0D | CR (carriage return) | 回車鍵 |
0000 1110 | 016 | 14 | 0x0E | SO (shift out) | 不用切換 |
0000 1111 | 017 | 15 | 0x0F | SI (shift in) | 啟用切換 |
0001 0000 | 020 | 16 | 0x10 | DLE (data link escape) | 數據鏈路轉義 |
0001 0001 | 021 | 17 | 0x11 | DC1 (device control 1) | 設備控制1 |
0001 0010 | 022 | 18 | 0x12 | DC2 (device control 2) | 設備控制2 |
0001 0011 | 023 | 19 | 0x13 | DC3 (device control 3) | 設備控制3 |
0001 0100 | 024 | 20 | 0x14 | DC4 (device control 4) | 設備控制4 |
0001 0101 | 025 | 21 | 0x15 | NAK (negative acknowledge) | 拒絕接收 |
0001 0110 | 026 | 22 | 0x16 | SYN (synchronous idle) | 同步空閑 |
0001 0111 | 027 | 23 | 0x17 | ETB (end of trans. block) | 結束傳輸塊 |
0001 1000 | 030 | 24 | 0x18 | CAN (cancel) | 取消 |
0001 1001 | 031 | 25 | 0x19 | EM (end of medium) | 媒介結束 |
0001 1010 | 032 | 26 | 0x1A | SUB (substitute) | 代替 |
0001 1011 | 033 | 27 | 0x1B | ESC (escape) | 換碼(溢出) |
0001 1100 | 034 | 28 | 0x1C | FS (file separator) | 文件分隔符 |
0001 1101 | 035 | 29 | 0x1D | GS (group separator) | 分組符 |
0001 1110 | 036 | 30 | 0x1E | RS (record separator) | 記錄分隔符 |
0001 1111 | 037 | 31 | 0x1F | US (unit separator) | 單元分隔符 |
0010 0000 | 040 | 32 | 0x20 | (space) | 空格 |
0010 0001 | 041 | 33 | 0x21 | ! | 嘆號 |
0010 0010 | 042 | 34 | 0x22 | " | 雙引號 |
0010 0011 | 043 | 35 | 0x23 | # | 井號 |
0010 0100 | 044 | 36 | 0x24 | $ | 美元符 |
0010 0101 | 045 | 37 | 0x25 | % | 百分號 |
0010 0110 | 046 | 38 | 0x26 | & | 和號 |
0010 0111 | 047 | 39 | 0x27 | ' | 閉單引號 |
0010 1000 | 050 | 40 | 0x28 | ( | 開括號 |
0010 1001 | 051 | 41 | 0x29 | ) | 閉括號 |
0010 1010 | 052 | 42 | 0x2A | * | 星號 |
0010 1011 | 053 | 43 | 0x2B | + | 加號 |
0010 1100 | 054 | 44 | 0x2C | , | 逗號 |
0010 1101 | 055 | 45 | 0x2D | - | 減號/破折號 |
0010 1110 | 056 | 46 | 0x2E | . | 句號 |
0010 1111 | 057 | 47 | 0x2F | / | 斜杠 |
0011 0000 | 060 | 48 | 0x30 | 0 | 字符0 |
0011 0001 | 061 | 49 | 0x31 | 1 | 字符1 |
0011 0010 | 062 | 50 | 0x32 | 2 | 字符2 |
0011 0011 | 063 | 51 | 0x33 | 3 | 字符3 |
0011 0100 | 064 | 52 | 0x34 | 4 | 字符4 |
0011 0101 | 065 | 53 | 0x35 | 5 | 字符5 |
0011 0110 | 066 | 54 | 0x36 | 6 | 字符6 |
0011 0111 | 067 | 55 | 0x37 | 7 | 字符7 |
0011 1000 | 070 | 56 | 0x38 | 8 | 字符8 |
0011 1001 | 071 | 57 | 0x39 | 9 | 字符9 |
0011 1010 | 072 | 58 | 0x3A | : | 冒號 |
0011 1011 | 073 | 59 | 0x3B | ; | 分號 |
0011 1100 | 074 | 60 | 0x3C | < | 小于 |
0011 1101 | 075 | 61 | 0x3D | = | 等號 |
0011 1110 | 076 | 62 | 0x3E | > | 大于 |
0011 1111 | 077 | 63 | 0x3F | ? | 問號 |
0100 0000 | 0100 | 64 | 0x40 | @ | 電子郵件符號 |
0100 0001 | 0101 | 65 | 0x41 | A | 大寫字母A |
0100 0010 | 0102 | 66 | 0x42 | B | 大寫字母B |
0100 0011 | 0103 | 67 | 0x43 | C | 大寫字母C |
0100 0100 | 0104 | 68 | 0x44 | D | 大寫字母D |
0100 0101 | 0105 | 69 | 0x45 | E | 大寫字母E |
0100 0110 | 0106 | 70 | 0x46 | F | 大寫字母F |
0100 0111 | 0107 | 71 | 0x47 | G | 大寫字母G |
0100 1000 | 0110 | 72 | 0x48 | H | 大寫字母H |
0100 1001 | 0111 | 73 | 0x49 | I | 大寫字母I |
01001010 | 0112 | 74 | 0x4A | J | 大寫字母J |
0100 1011 | 0113 | 75 | 0x4B | K | 大寫字母K |
0100 1100 | 0114 | 76 | 0x4C | L | 大寫字母L |
0100 1101 | 0115 | 77 | 0x4D | M | 大寫字母M |
0100 1110 | 0116 | 78 | 0x4E | N | 大寫字母N |
0100 1111 | 0117 | 79 | 0x4F | O | 大寫字母O |
0101 0000 | 0120 | 80 | 0x50 | P | 大寫字母P |
0101 0001 | 0121 | 81 | 0x51 | Q | 大寫字母Q |
0101 0010 | 0122 | 82 | 0x52 | R | 大寫字母R |
0101 0011 | 0123 | 83 | 0x53 | S | 大寫字母S |
0101 0100 | 0124 | 84 | 0x54 | T | 大寫字母T |
0101 0101 | 0125 | 85 | 0x55 | U | 大寫字母U |
0101 0110 | 0126 | 86 | 0x56 | V | 大寫字母V |
0101 0111 | 0127 | 87 | 0x57 | W | 大寫字母W |
0101 1000 | 0130 | 88 | 0x58 | X | 大寫字母X |
0101 1001 | 0131 | 89 | 0x59 | Y | 大寫字母Y |
0101 1010 | 0132 | 90 | 0x5A | Z | 大寫字母Z |
0101 1011 | 0133 | 91 | 0x5B | [ | 開方括號 |
0101 1100 | 0134 | 92 | 0x5C | \ | 反斜杠 |
0101 1101 | 0135 | 93 | 0x5D | ] | 閉方括號 |
0101 1110 | 0136 | 94 | 0x5E | ^ | 脫字符 |
0101 1111 | 0137 | 95 | 0x5F | _ | 下劃線 |
0110 0000 | 0140 | 96 | 0x60 | ` | 開單引號 |
0110 0001 | 0141 | 97 | 0x61 | a | 小寫字母a |
0110 0010 | 0142 | 98 | 0x62 | b | 小寫字母b |
0110 0011 | 0143 | 99 | 0x63 | c | 小寫字母c |
0110 0100 | 0144 | 100 | 0x64 | d | 小寫字母d |
0110 0101 | 0145 | 101 | 0x65 | e | 小寫字母e |
0110 0110 | 0146 | 102 | 0x66 | f | 小寫字母f |
0110 0111 | 0147 | 103 | 0x67 | g | 小寫字母g |
0110 1000 | 0150 | 104 | 0x68 | h | 小寫字母h |
0110 1001 | 0151 | 105 | 0x69 | i | 小寫字母i |
0110 1010 | 0152 | 106 | 0x6A | j | 小寫字母j |
0110 1011 | 0153 | 107 | 0x6B | k | 小寫字母k |
0110 1100 | 0154 | 108 | 0x6C | l | 小寫字母l |
0110 1101 | 0155 | 109 | 0x6D | m | 小寫字母m |
0110 1110 | 0156 | 110 | 0x6E | n | 小寫字母n |
0110 1111 | 0157 | 111 | 0x6F | o | 小寫字母o |
0111 0000 | 0160 | 112 | 0x70 | p | 小寫字母p |
0111 0001 | 0161 | 113 | 0x71 | q | 小寫字母q |
0111 0010 | 0162 | 114 | 0x72 | r | 小寫字母r |
0111 0011 | 0163 | 115 | 0x73 | s | 小寫字母s |
0111 0100 | 0164 | 116 | 0x74 | t | 小寫字母t |
0111 0101 | 0165 | 117 | 0x75 | u | 小寫字母u |
0111 0110 | 0166 | 118 | 0x76 | v | 小寫字母v |
0111 0111 | 0167 | 119 | 0x77 | w | 小寫字母w |
0111 1000 | 0170 | 120 | 0x78 | x | 小寫字母x |
0111 1001 | 0171 | 121 | 0x79 | y | 小寫字母y |
0111 1010 | 0172 | 122 | 0x7A | z | 小寫字母z |
0111 1011 | 0173 | 123 | 0x7B | { | 開花括號 |
0111 1100 | 0174 | 124 | 0x7C | | | 垂線 |
0111 1101 | 0175 | 125 | 0x7D | } | 閉花括號 |
0111 1110 | 0176 | 126 | 0x7E | ~ | 波浪號 |
0111 1111 | 0177 | 127 | 0x7F | DEL (delete) | 刪除 |
*請認真填寫需求信息,我們會在24小時內與您取得聯系。