swagger-ui 轉換成文檔

最近在用swagger寫API手冊，寫一堆註解後，啓動Java工程，API文檔就自動生成了，打開swagger-ui.html，效果是這樣的。上面能夠執行RestAPI，可是用來閱讀，很是不得勁。

由於，咱們想要下面這樣的，哪裏不會點哪裏。

怎麼獲得這種效果呢？swagger2markup + AsciiDoc能夠幫你達成目標。

Swagger2markup

swagger2markup是一個Java庫，用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，好比：AsciiDoc、Markdown。可是這種方式進行swagger to markup的轉換要編碼初始化，作一堆事情，侵入性較大。

swagger2markup-cli 是一種將 swagger json文件轉換爲 Markdown 或 AsciiDoc 的命令行工具。不須要寫代碼，就能夠進行轉換。

我更喜歡swagger2markup-cli這種侵入性小的轉換方式，它的主要操做步驟以下

1. 下載swagger2markup-cli到本地(本地已安裝jre)
   去github https://github.com/Swagger2Ma... , 下載最新代碼，編譯一個jar包便可。
   默認的swagger2markup-cli生成英文的AsciiDoc文檔，若是要生成中文markdown文檔，須要將語言設置爲中文，將文檔格式設置爲Markdown。 配置以下，建議將這些配置保存到文檔config.properties中。

   swagger2markup.markupLanguage=MARKDOWN
   swagger2markup.outputLanguage=ZH

2. 獲取swagger-json文件的路徑
   採用swagger 註解的Spring Boot工程啓動後，就能夠從 URL "base路徑"/v2/api-docs接口能夠得到 swagger-json文件
3. 執行命令 swagger2markup-cli 生成markdown

   java -jar swagger2markup-cli-1.3.3.jar convert -i http://127.0.0.1:8090/api/v1/v2/api-docs -c ./config.properties -f lsm
   -i 指定swagger json文件能夠是url地址
   -c 指定配置文件
   -f 指定目標文件地址，注意不須要帶後綴

執行命令後你就能夠獲得markdown文件或AsciiDoc文件，但markdown顯示後的效果是這樣的，並無咱們期待的側邊欄。

AsciiDoctor

Asciidoc 是一種文檔寫做語言，能夠展現出比markdown更好的格式效果。確實如此，我原本想先生成markdown再將markdown格式化，但搜索了半天，沒有好但方案。因而我就選用了AsciiDoc，AsciiDoc有比較好但工具軟件AsciiDoctor。基於這個工具能夠簡單快捷但生成類JavaDoc html文件，而且顯示效果更好。

1. 安裝
   Asciidoctor 使用ruby寫的，我安裝是使用gem安裝的，gem install Asciidoctor便可。其餘環境安裝方法請到Asciidoctor官網查詢。https://asciidoctor.org/docs/...
2. 轉換
   執行以下命令，便可獲得 lsm.html，顯示效果以下圖
   asciidoctor -d book -a toc=left -a sectnums lsm.adoc
   -d 生成文件類型
   -a toc=left 指定目錄到左側
   -a sectnums 指定生成的文件帶section編

至此搞定收工，但願你也能擁有一個滿意的API 文檔。