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