當 Swagger 遇上 Torna，瞬間高大上了！

macrozheng發表於2021-11-16
Swagger
Swagger作為一款非常流行的API文件生成工具，相信很多小夥們都在用！用多了可能會覺得它介面醜、功能弱。今天給大家推薦一款工具Torna，配合Swagger使用可以搭建介面漂亮、功能強大的API文件網站，希望對大家有所幫助！

SpringBoot實戰電商專案mall（50k+star）地址：https://github.com/macrozheng/mall

Torna簡介

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

  • 文件管理：支援介面文件增刪改查、介面除錯、字典管理及匯入匯出功能；
  • 許可權管理：支援介面文件的許可權管理，同時有訪客、開發者、管理員三種角色；
  • 雙模式：獨創的雙模式，管理模式可以用來編輯文件內容，瀏覽模式純粹查閱文件，介面無其它元素干擾。

Torna專案架構

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

  • 下載成功後，將程式碼匯入到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

使用

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 {

    @Test
    public void pushDoc(){
        // 將文件推送到Torna服務中去，預設查詢resources下的torna.json
        SwaggerPlugin.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...

本文 GitHub https://github.com/macrozheng/mall-learning 已經收錄，歡迎大家Star！

相關文章