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.

# 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

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/

.

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

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. docker pull tanghc2020/torna:latest Copy application.properties to /mydata/torna/config and adjust the database settings.

# 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

Run the container:

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

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:

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

Add a torna.json configuration file under resources (see example below).

{
  "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
}

Invoke SwaggerPlugin.pushDoc() to push the API documentation to Torna.

@RunWith(SpringRunner.class)
@SpringBootTest
public class MallTinyApplicationTests {

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

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:

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

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