當 Swagger 遇上 Torna，瞬間高大上了！
Swagger作為一款非常流行的API文檔生成工具，相信很多小伙們都在用！用多了可能會覺得它界面丑、功能弱。今天給大家推薦一款工具Torna，配合Swagger使用可以搭建界面漂亮、功能強大的API文檔網(wǎng)站，希望對大家有所幫助！
Torna簡介
Torna是一套企業(yè)級接口文檔解決方案，可以配合Swagger使用。它具有如下功能：
文檔管理：支持接口文檔增刪改查、接口調(diào)試、字典管理及導入導出功能； 權限管理：支持接口文檔的權限管理，同時有訪客、開發(fā)者、管理員三種角色； 雙模式：獨創(chuàng)的雙模式， 管理模式可以用來編輯文檔內(nèi)容，瀏覽模式純粹查閱文檔，界面無其它元素干擾。
Torna項目架構(gòu)
Torna是一個前后端分離項目，后端使用SpringBoot+MyBatis來實現(xiàn)，前端使用Vue+ElementUI來實現(xiàn)，技術棧非常主流！它不僅可以搭建API文檔網(wǎng)站，還是個非常好的學習項目，讓我們先來看看它的項目架構(gòu)。
首先我們需要下載Torna的源碼，下載地址：https://gitee.com/durcframework/torna
下載成功后，將代碼導入到IDEA中，項目結(jié)構(gòu)如下；
我們再來看下 server模塊的結(jié)構(gòu)，一個非常標準的SpringBoot項目；
再來看下 front模塊的結(jié)構(gòu)，一個非常標準的Vue項目，值得學習！
安裝
接下來我們把Torna運行起來，體驗一下它的功能，這里提供Windows和Linux兩種安裝方式。
Windows
下面我們來介紹Torna在Windows下的安裝方法，如果你想深入學習Torna的話可以采用此種方式。
后端運行
首先創(chuàng)建一個數(shù)據(jù)庫 torna，然后導入項目中的mysql.sql腳本，導入成功后，表結(jié)構(gòu)如下；
修改項目的配置文件 server/boot/src/main/resources/application.properties，修改對應的數(shù)據(jù)庫連接配置；
# Server port
server.port=7700
# MySQL host
mysql.host=localhost:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root
然后運行項目啟動類 TornaApplication的main方法，控制臺打印如下信息表示啟動成功。
前端運行
進入前端項目目錄 front，運行npm install命令安裝依賴；
此時如果遇到 node-sass無法安裝的情況，可以直接使用如下命令安裝；
npm?i?node-sass?--sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
依賴安裝完成后，可以通過 npm run dev命令啟動項目，啟動成功后訪問地址：http://localhost:9530/
通過體驗賬號密碼 [email protected]:123456可以訪問Torna服務，界面還是不錯的！
Linux
在Linux下使用Docker安裝Torna是非常簡單的，如果你只想用Torna來做API文檔服務的話可以采用這種方式。
首先我們需要下載Torna的Docker鏡像；
docker?pull?tanghc2020/torna:latest
下載完成后將配置文件 application.properties拷貝配置文件到/mydata/torna/config目錄下，并修改數(shù)據(jù)庫配置；
# Server port
server.port=7700
# MySQL host
mysql.host=192.168.3.101:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root
然后通過如下命令運行Torna服務；
docker?run?-p?7700:7700?--name?torna?\
-v?/mydata/torna/config:/torna/config?\
-d?tanghc2020/torna:latest
由于鏡像中直接包含了前端和后端項目，所以可以直接使用，訪問地址：http://192.168.3.101:7700
使用
Torna支持從多種工具導入接口文檔，包括Swagger、smart-doc、OpenAPI、Postman等，接下來我們來體驗下它的功能！
結(jié)合Swagger使用
Torna能大大增強Swagger的功能，并且界面足夠美觀，下面我們來體驗下！
在使用之前，我們需要在Torna中進行配置才行，首先我們來配置一個開放用戶，新建一個 macro的賬號，記住AppKey和Secret；
然后創(chuàng)建一個項目 mall-tiny-trona；
接下來創(chuàng)建一個模塊，打開 OpenAPI標簽，獲取請求路徑和token；
之后在使用Swagger的項目中集成Torna插件，非常簡單，添加如下依賴即可；
<dependency>
????<groupId>cn.tornagroupId>
????<artifactId>swagger-pluginartifactId>
????<version>1.2.6version>
????<scope>testscope>
dependency>
然后在 resources目錄下添加配置文件torna.json，配置說明參考注釋即可；
{
??//?開啟推送
??"enable":?true,
??//?掃描package，多個用;隔開
??"basePackage":?"com.macro.mall.tiny.controller",
??//?推送URL，IP端口對應Torna服務器
??"url":?"http://localhost:7700/api",
??//?appKey
??"appKey":?"20211103905498418195988480",
??//?secret
??"secret":?"~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
??//?模塊token
??"token":?"74365d40038d4f648ae65a077d956836",
??//?調(diào)試環(huán)境，格式：環(huán)境名稱,調(diào)試路徑，多個用"|"隔開
??"debugEnv":?"test,http://localhost:8088",
??//?推送人
??"author":?"macro",
??//?打開調(diào)試:true/false
??"debug":?true,
??//?是否替換文檔，true：替換，false：不替換（追加）。默認：true
??"isReplace":?true
}
接下來通過調(diào)用 SwaggerPlugin的pushDoc方法來推送接口文檔到Torna；
@RunWith(SpringRunner.class)
@SpringBootTest
public?class?MallTinyApplicationTests?{
????@Test
????public?void?pushDoc(){
????????//?將文檔推送到Torna服務中去，默認查找resources下的torna.json
????????SwaggerPlugin.pushDoc();
????}
}
推送成功后，在接口列表將顯示如下接口信息；
查看一下接口的詳細信息，還是很全面的，界面也不錯！
把我們的項目運行起來，就可以直接在上面進行接口調(diào)試了，調(diào)用下登錄接口試試；
如果我們想設置公共請求頭的話，比如用于登錄認證的 Authorization頭，可以在模塊配置中進行配置；
在后端接口沒有完成前，我們?nèi)绻枰狹ock數(shù)據(jù)的話，可以使用Mock功能；
這里我們對登錄接口進行了一下Mock，當然你也可以使用Mock腳本，這下只要接口定義好，前端就可以使用Mock的數(shù)據(jù)聯(lián)調(diào)了。
結(jié)合smart-doc使用
smart-doc是一款無注解侵入的API文檔生成工具，具體使用可以參考《smart-doc使用教程》 ，這里介紹下它與Torna結(jié)合使用。
首先修改 mall-tiny-smart-doc項目的smart-doc配置文件smart-doc.json，添加如下關于Torna的配置；
{
??//?torna平臺對接appKey
??"appKey":?"20211103905498418195988480",
??//torna平臺appToken
??"appToken":?"b6c50f442eb348f48867d85f4ef2eaea",
??//torna平臺secret
??"secret":?"~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
??//torna平臺地址，填寫自己的私有化部署地址
??"openUrl":?"http://localhost:7700/api",
??//測試項目接口環(huán)境
??"debugEnvName":"測試環(huán)境",
??//測試項目接口地址
??"debugEnvUrl":"http://localhost:8088"
}
由于smart-doc的Maven插件已經(jīng)自帶推送文檔到Torna的功能，我們只需雙擊 smart-doc:torna-rest按鈕即可；
接下來在Torna中，我們就可以看到相關的接口文檔了，非常方便！
總結(jié)
當一種工具變得越來越流行，但是某些功能需求又滿足不了時，往往會有一些增強工具產(chǎn)生，Torna對于Swagger來說正是這樣一種工具。Torna的文檔界面和調(diào)試功能明顯比Swagger高大上多了，而且還增加了權限管理功能，文檔的安全性大大增強，大家覺得不錯的話可以嘗試下它！
參考資料
官方文檔：http://torna.cn/
項目源碼地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-torna
我是 Guide哥，一個工作2年有余，接觸編程已經(jīng)6年有余的程序員。大三開源 JavaGuide，目前已經(jīng) 100k+ Star。未來幾年，希望持續(xù)完善 JavaGuide，爭取能夠幫助更多學習 Java 的小伙伴！共勉！凎！點擊即可了解我的個人經(jīng)歷。
