?

?Swagger作為一款非常流行的API文檔生成工具，相信很多小伙們都在用！用多了可能會覺得它界面丑、功能弱。今天給大家推薦一款工具Torna，配合Swagger使用可以搭建界面漂亮、功能強大的API文檔網站，希望對大家有所幫助！

?

Torna簡介

Torna是一套企業級接口文檔解決方案，可以配合Swagger使用。它具有如下功能：

• 文檔管理：支持接口文檔增刪改查、接口調試、字典管理及導入導出功能；

• 權限管理：支持接口文檔的權限管理，同時有訪客、開發者、管理員三種角色；

• 雙模式：獨創的雙模式，管理模式可以用來編輯文檔內容，瀏覽模式純粹查閱文檔，界面無其它元素干擾。

?

Torna項目架構

Torna是一個前后端分離項目，后端使用SpringBoot+MyBatis來實現，前端使用Vue+ElementUI來實現，技術棧非常主流！它不僅可以搭建API文檔網站，還是個非常好的學習項目，讓我們先來看看它的項目架構。

• 首先我們需要下載Torna的源碼，下載地址：https://gitee.com/durcframework/torna

• 下載成功后，將代碼導入到IDEA中，項目結構如下；

• 我們再來看下server模塊的結構，一個非常標準的SpringBoot項目；

• 再來看下front模塊的結構，一個非常標準的Vue項目，值得學習！

?

安裝

接下來我們把Torna運行起來，體驗一下它的功能，這里提供Windows和Linux兩種安裝方式。

Windows

下面我們來介紹Torna在Windows下的安裝方法，如果你想深入學習Torna的話可以采用此種方式。

后端運行

• 首先創建一個數據庫torna，然后導入項目中的mysql.sql腳本，導入成功后，表結構如下；

• 修改項目的配置文件server/boot/src/main/resources/application.properties，修改對應的數據庫連接配置；

# 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/

• 通過體驗賬號密碼admin@torna.cn:123456可以訪問Torna服務，界面還是不錯的！

Linux

在Linux下使用Docker安裝Torna是非常簡單的，如果你只想用Torna來做API文檔服務的話可以采用這種方式。

• 首先我們需要下載Torna的Docker鏡像；

docker?pull?tanghc2020/torna:latest

• 下載完成后將配置文件application.properties拷貝配置文件到/mydata/torna/config目錄下，并修改數據庫配置；

# 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等，接下來我們來體驗下它的功能！

結合Swagger使用

Torna能大大增強Swagger的功能，并且界面足夠美觀，下面我們來體驗下！

• 在使用之前，我們需要在Torna中進行配置才行，首先我們來配置一個開放用戶，新建一個macro的賬號，記住AppKey和Secret；

• 然后創建一個項目mall-tiny-trona；

• 接下來創建一個模塊，打開OpenAPI標簽，獲取請求路徑和token；

• 之后在使用Swagger的項目中集成Torna插件，非常簡單，添加如下依賴即可；

<!--?Torna?Swagger?插件?--> <dependency><groupId>cn.torna</groupId><artifactId>swagger-plugin</artifactId><version>1.2.6</version><scope>test</scope> </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",//?調試環境，格式：環境名稱,調試路徑，多個用"|"隔開"debugEnv":?"test,http://localhost:8088",//?推送人"author":?"macro",//?打開調試:true/false"debug":?true,//?是否替換文檔，true：替換，false：不替換（追加）。默認：true"isReplace":?true }

• 接下來通過調用SwaggerPlugin的pushDoc方法來推送接口文檔到Torna；

@RunWith(SpringRunner.class) @SpringBootTest public?class?MallTinyApplicationTests?{@Testpublic?void?pushDoc(){//?將文檔推送到Torna服務中去，默認查找resources下的torna.jsonSwaggerPlugin.pushDoc();}}

• 推送成功后，在接口列表將顯示如下接口信息；

• 查看一下接口的詳細信息，還是很全面的，界面也不錯！

• 把我們的項目運行起來，就可以直接在上面進行接口調試了，調用下登錄接口試試；

• 如果我們想設置公共請求頭的話，比如用于登錄認證的Authorization頭，可以在模塊配置中進行配置；

• 在后端接口沒有完成前，我們如果需要Mock數據的話，可以使用Mock功能；

• 這里我們對登錄接口進行了一下Mock，當然你也可以使用Mock腳本，這下只要接口定義好，前端就可以使用Mock的數據聯調了。

結合smart-doc使用

smart-doc是一款無注解侵入的API文檔生成工具，具體使用可以參考《smart-doc使用教程》 ，這里介紹下它與Torna結合使用。

• 首先修改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",//測試項目接口環境"debugEnvName":"測試環境",//測試項目接口地址"debugEnvUrl":"http://localhost:8088" }

• 由于smart-doc的Maven插件已經自帶推送文檔到Torna的功能，我們只需雙擊smart-doc:torna-rest按鈕即可；

• 接下來在Torna中，我們就可以看到相關的接口文檔了，非常方便！

?

總結

當一種工具變得越來越流行，但是某些功能需求又滿足不了時，往往會有一些增強工具產生，Torna對于Swagger來說正是這樣一種工具。Torna的文檔界面和調試功能明顯比Swagger高大上多了，而且還增加了權限管理功能，文檔的安全性大大增強，大家覺得不錯的話可以嘗試下它！

參考資料

官方文檔：http://torna.cn/

項目源碼地址

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-torna

有道無術，術可成；有術無道，止于術

歡迎大家關注Java之道公眾號

好文章，我在看??

總結

以上是生活随笔為你收集整理的当 Swagger 遇上 Torna，瞬间高大上了！的全部內容，希望文章能夠幫你解決所遇到的問題。

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