介面文件解決方案！企業級的介面文件管理平臺！

Java陈序员發表於2024-08-19

大家好，我是 Java陳序員。

在企業開發中，涉及到很多個專案，每個專案都有一套自己的介面文件，維護起來不是很方便，需要一個統一的介面文件管理平臺來進行管理。

今天，給大家介紹一個開源的企業級介面文件管理平臺！

關注微信公眾號：【Java陳序員】，獲取開源專案分享、AI副業分享、超200本經典計算機電子書籍等。

專案介紹

Torna —— 一款介面文件解決方案，目標是讓介面文件管理變得更加方便、快捷。採用團隊協作的方式管理和維護介面文件，將不同形式的文件納入進來統一維護。

Torna 作為一款企業級介面文件管理平臺，實現了統一管理專案介面文件的功能，並且支援線上除錯、遊客預覽。

此外，可以使用 smart-doc 無侵入完成 Java 原始碼和註釋提取生成 API 文件，然後自動將文件推送到 Torna 介面文件管理平臺，從而實現介面預覽、介面除錯。

smart-doc 的介紹詳見：零侵入！試試這款Api介面文件生成器！

如果一些舊專案使用 Postman、 Swagger 或者 SpringDoc 來進行介面文件管理，Torna 也提供了對應的外掛來整合！

功能特色：

  • 文件管理：支援介面文件增刪改查、匯入匯出、OpenAPI接入、字典管理、介面除錯
  • 許可權管理：以專案組的形式管理介面，各專案組之間介面互不影響，同時有訪客、開發者、管理員三種角色，每種角色有用不同許可權
  • 雙模式：提供【管理模式】、【瀏覽模式】雙模式，管理模式用來編輯文件內容，瀏覽模式純粹查閱文件，介面無其它元素干擾

介面預覽

登入

空間列表

專案列表

應用管理

新增文件

文件預覽

介面除錯

介面Mock

常量管理

版本管理

預覽模式

快速上手

前置準備

開發環境：

  • Java8
  • MySQL5.6.5+
  • Maven3
  • Node.js12

拉取程式碼：

git clone https://gitee.com/durcframework/torna.git

目錄結構：

front: 前端工程
plugin: 外掛
script: 輔助指令碼
sdk: OpenAPI對應的SDK
server: 服務端工程
mysql.sql：資料庫指令碼

後端服務

1、將整個專案以 Maven 專案的形式匯入到 IDEA 中

2、執行指令碼 mysql.sql 初始化資料

3、修改配置檔案 server/boot/src/main/resources/application.properties 中的資料庫配置資訊

4、執行主啟動類 server/boot/src/main/java/cn/torna/TornaApplication.jav 啟動專案

前端服務

1、進入前端專案

cd front

2、安裝依賴

npm isntall

3、啟動專案

npm run dev

4、瀏覽器訪問：

http://localhost:9530/#/

預設使用者名稱密碼：admin/123456

部署 Torna 可以使用原始碼打包的方式進行部署，也可以使用專案提供的指令碼進行部署，或者是使用 Docker 的方式進行部署，具體的部署方式可以參考官方文件。

使用 smart-doc 推送文件

使用 smart-doc 可以無侵入完成提取註釋生成 API 文件，並自動將文件推送到 Torna 平臺。

smart-doc 外掛是依賴於介面的原始碼進行分析和生成文件，因此需按照 JavaDoc 的標準編寫註釋。

1、在 Torna 平臺先建立一個專案，在 OpenAPI 中獲取請求路徑和 token

2、在專案中引入 smart-doc 外掛

<plugins>
    <!-- smart-doc外掛 -->
    <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>3.0.2</version>
        <configuration>
            <!--指定生成文件的使用的配置檔案-->
            <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
            <!--指定專案名稱-->
            <projectName>收銀臺後臺服務</projectName>
        </configuration>
        <executions>
            <execution>
                <phase>package</phase>
            </execution>
        </executions>
    </plugin>
</plugins>

3、在專案的 resources 目錄下新增一個 smart-doc.json 檔案

{
  "outPath": "target/doc",
  "projectName": "收銀臺後臺服務",
  "packageFilters": "com.codechen.pay.controller.*",
  "openUrl": "http://localhost:9530/api",
  "appToken": "27ffa73c8794454abc58f481ada23766",
  "debugEnvName":"本地環境",
  "debugEnvUrl":"http://127.0.0.1:8080",
  "tornaDebug": true,
  "replace": true
}

openUrl 和 appToken 在應用的 OpenAPI 中獲取。

4、執行外掛，將文件推送到 Torna 平臺

或者在專案根目錄輸入 Maven 命令：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :shop-web -am

除了使用 smart-doc 外掛推送文件外，專案還提供了 Swagger 文件、SpringDoc 文件推送的外掛，相應的整合可參考專案文件。

Torna 可以說是一個功能十分強大的介面管理平臺，完美適用於企業級開發。如果需要搭建一個企業級的介面管理平臺，可以考慮使用 Torna.

專案地址：https://gitee.com/durcframework/torna
線上文件：https://torna.cn/

最後

推薦的開源專案已經收錄到 GitHub 專案，歡迎 Star：

https://github.com/chenyl8848/great-open-source-project

或者訪問網站，進行線上瀏覽：

https://chencoding.top:8090/#/

大家的點贊、收藏和評論都是對作者的支援，如文章對你有幫助還請點贊轉發支援下，謝謝！

相關文章