Boost Your API Docs: How to Install and Use Torna with Swagger

Swagger is a popular API documentation generation tool, but its interface can be unattractive and its features limited; Torna is a complementary tool that, when used with Swagger, creates a beautiful and powerful API documentation website.

Torna Overview

Torna is an enterprise‑grade API documentation solution that works with Swagger and offers the following features:

Document management: supports CRUD operations on API docs, interface debugging, dictionary management, and import/export.

Permission management: provides role‑based access with Visitor, Developer, and Administrator roles.

Dual mode:

Management mode

for editing documentation and

Browse mode

for pure read‑only viewing without distractions.

Torna Project Architecture

Torna is a front‑back separated project; the backend uses SpringBoot + MyBatis, and the frontend uses Vue + ElementUI, forming a mainstream tech stack that serves both as an API documentation site and a valuable learning project.

Download Torna source code from https://gitee.com/durcframework/torna .

Import the code into IDEA; the project structure appears as shown.

Examine the

server

module – a standard SpringBoot project.

Examine the

front

module – a standard Vue project worth learning.

Installation

The following sections describe how to run Torna on Windows and Linux, providing two installation methods.

Windows

This method is suitable for deep learning of Torna on Windows.

Backend Run

Create a database named

torna

and import the

mysql.sql

script from the project; the resulting table structure is shown.

Modify the configuration file

server/boot/src/main/resources/application.properties

to set the database connection.

<code># Server port
server.port=7700

# MySQL host
mysql.host=localhost:3306
# Schema name
mysql.schema=torna
# Ensure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root
</code>

Run the main method of

TornaApplication

; a console message indicates successful startup.

Frontend Run

Enter the

front

directory and execute

npm install

to install dependencies.

If

node-sass

fails to install, run

npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/

.

<code>npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/</code>

After dependencies are installed, start the project with

npm run dev

and access

http://localhost:9530/

.

Log in with the demo account

[email protected]:123456

to explore the Torna UI.

Linux

Using Docker on Linux provides a quick way to run Torna as an API documentation service.

Pull the Torna Docker image.

<code>docker pull tanghc2020/torna:latest</code>

Copy

application.properties

to

/mydata/torna/config

and adjust the database settings.

<code># Server port
server.port=7700

# MySQL host
mysql.host=192.168.3.101:3306
# Schema name
mysql.schema=torna
# Ensure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root
</code>

Run the container:

<code>docker run -p 7700:7700 --name torna \
 -v /mydata/torna/config:/torna/config \
 -d tanghc2020/torna:latest</code>

Usage

Torna can import API definitions from Swagger, smart‑doc, OpenAPI, Postman, etc.

Integrating with Swagger

Torna enhances Swagger with a more attractive UI and additional features.

Create an open user (macro) in Torna and note the

AppKey

and

Secret

.

Create a project named

mall-tiny-torna

.

Add a module, open the

OpenAPI

tab, and obtain the request path and token.

Add the Torna Swagger plugin dependency to the Swagger project:

<code><!-- Torna Swagger plugin -->
<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>swagger-plugin</artifactId>
    <version>1.2.6</version>
    <scope>test</scope>
</dependency>
</code>

Add a

torna.json

configuration file under

resources

(see example below).

<code>{
  "enable": true,
  "basePackage": "com.macro.mall.tiny.controller",
  "url": "http://localhost:7700/api",
  "appKey": "20211103905498418195988480",
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  "token": "74365d40038d4f648ae65a077d956836",
  "debugEnv": "test,http://localhost:8088",
  "author": "macro",
  "debug": true,
  "isReplace": true
}
</code>

Invoke

SwaggerPlugin.pushDoc()

to push the API documentation to Torna.

<code>@RunWith(SpringRunner.class)
@SpringBootTest
public class MallTinyApplicationTests {

    @Test
    public void pushDoc() {
        // Push documentation to Torna (default looks for torna.json in resources)
        SwaggerPlugin.pushDoc();
    }
}
</code>

After a successful push, the interface list displays the imported APIs, which can be inspected and tested directly in Torna.

Configure common request headers such as

Authorization

in the module settings.

Use Torna's Mock feature to provide mock data before the backend implementation is complete.

Integrating with smart‑doc

smart‑doc is a zero‑annotation API documentation tool; the following shows how to connect it with Torna.

Update the

smart-doc.json

of the

mall-tiny-smart-doc

project with Torna configuration:

<code>{
  "appKey": "20211103905498418195988480",
  "appToken": "b6c50f442eb348f48867d85f4ef2eaea",
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  "openUrl": "http://localhost:7700/api",
  "debugEnvName": "测试环境",
  "debugEnvUrl": "http://localhost:8088"
}
</code>

Run the Maven goal

smart-doc:torna-rest

to push the documentation to Torna.

Conclusion

When a tool becomes popular but lacks certain features, complementary tools emerge; Torna enhances Swagger with a superior UI, debugging capabilities, and permission management, greatly improving documentation security and usability.

References

Official documentation: http://torna.cn/

Source Code

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