When Swagger meets Torna, instantly tall!

Swagger is a very popular API document generation tool, I believe many guys use it! If you use it too much, you might find it ugly and weak. Today, I would like to recommend Torna, which can be used with Swagger to build a beautiful interface and powerful API document website. I hope it will be helpful to you!

SpringBoot e-commerce project mall (50K + STAR) address: github.com/macrozheng/…

Torna profile

Torna is an enterprise-class interface documentation solution that works with Swagger. It has the following functions:

Document management: support interface document adding, deleting, modifying and searching, interface debugging, dictionary management and import and export functions;
Permission management: Supports the permission management of interface documents, including visitors, developers, and administrators.
Dual mode: original dual mode,Management modeCan be used to edit the contents of a document,Browse modePure document access, no other interface elements.

Torna Project architecture

Torna is a front end separation project, the back end using SpringBoot+MyBatis to achieve, the front end using Vue+ElementUI to achieve, technology stack is very mainstream! Not only can it build API documentation sites, but it’s also a great learning project. Let’s take a look at its project architecture first.

First we need to download the source of Torna at gitee.com/durcframewo…

After downloading successfully, import the code into IDEA, and the project structure is as follows;

Let’s look at it againserverModule structure, a very standard SpringBoot project;

Look at thefrontModule structure, a very standard Vue project, worth learning!

The installation

Let’s get Torna up and running to see what it can do. It’s available for Windows and Linux installation.

Windows

Here’s how to install Torna on Windows, if you want to learn more about Torna.

The back-end running

Start by creating a databasetorna, and then import into the projectmysql.sqlAfter the script is imported successfully, the table structure is as follows.

Modify the configuration file of the projectserver/boot/src/main/resources/application.properties, modify the corresponding database connection configuration;

# 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
Copy the code

Then run the project startup classTornaApplicationIf the following information is displayed on the console, the startup is successful.

The front running

Go to the front-end project directoryfrontRun,npm installCommand install dependencies;

At this point, if you encounternode-sassIf the installation fails, run the following command to install it:

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

After the dependency installation is complete, you can passnpm run devRun the following command to start the project:http://localhost:9530/

Experience the account password[email protected]:123456Access to Torna services, the interface is good!

Linux

Installing Torna using Docker under Linux is very simple, if you only want Torna for API documentation services.

First, we need to download the Docker image of Torna;

docker pull tanghc2020/torna:latest
Copy the code

The file will be configured after downloadingapplication.propertiesCopy the configuration file to/mydata/torna/configAnd modify the database configuration.

# 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
Copy the code

Then run the following command to run the Torna service:

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

Due to direct the image containing the front-end and back-end projects, so can be used directly, access to the address: http://192.168.3.101:7700

use

Torna supports the import of interface documents from various tools, including Swagger, Smart-Doc, OpenAPI, Postman, etc. Let’s check it out!

Use in combination with Swagger

Torna can greatly enhance the function of Swagger, and the interface is beautiful enough, let’s experience it below!

Before using it, we need to configure it in Torna. First we need to configure an open user and create a new onemacroAccount number, rememberAppKeyandSecret;

Then create a projectmall-tiny-trona;

Next create a module and open itOpenAPITag, getRequest pathandtoken;

Then integrate Torna into projects that use Swagger, very simple, add the following dependencies;

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

Then, inresourcesAdd a configuration file to the directorytorna.json, the configuration instructions refer to the notes;

{
  // Enable push
  "enable": true.// Scan package; separated
  "basePackage": "com.macro.mall.tiny.controller".// Push URL. IP port corresponds to Torna server
  "url": "http://localhost:7700/api".// appKey
  "appKey": "20211103905498418195988480".// secret
  "secret": "~#ZS~! *2B3I01vbW0f9iKH,rzj-%Xv^Q"./ / module token
  "token": "74365d40038d4f648ae65a077d956836"./ / debugging environment, format: name of the environment, debugging paths, multiple use "|"
  "debugEnv": "test,http://localhost:8088"./ / push
  "author": "macro".// Enable debugging :true/false
  "debug": true.// Whether to replace the document, true: replace, false: do not replace (append). Default: true,
  "isReplace": true
}
Copy the code

Next, by callingSwaggerPluginthepushDocMethod to push interface documents to Torna;

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

    @Test
    public void pushDoc(a){
        // Push the document to the Torna service, looking for torna.json under Resources by defaultSwaggerPlugin.pushDoc(); }}Copy the code

After the push succeeds, the following interface information is displayed in the interface list.

View the details of the interface, or very comprehensive, interface is also good!

Run our project, you can directly in the above interface debugging, call login interface try;

If we want to set a common request header, such as one for login authenticationAuthorizationHead, can be inThe module configurationTo configure;

Until the back-end interface is complete, we can use Mock functionality if we need Mock data.

Here we Mock the login interface. You can also use a Mock script. Once the interface is defined, the front end can use the Mock data.

Use in combination with smart-doc

Smart-doc is a non-annotated API document generation tool. Please refer to the Smart-Doc Tutorial to see how to use it in conjunction with Torna.

The first changemall-tiny-smart-docSmart-doc configuration file for the projectsmart-doc.json, add the following configuration about Torna;

{
  // Torna connects to appKey
  "appKey": "20211103905498418195988480"./ / appToken torna platform
  "appToken": "b6c50f442eb348f48867d85f4ef2eaea"./ / secret torna platform
  "secret": "~#ZS~! *2B3I01vbW0f9iKH,rzj-%Xv^Q".// Torna platform address, fill in your private deployment address
  "openUrl": "http://localhost:7700/api".// Test the project interface environment
  "debugEnvName":"Test environment".// Test item interface address
  "debugEnvUrl":"http://localhost:8088"
}
Copy the code

Since smart-Doc’s Maven plugin already has the ability to push documents to Torna, we just need to double clicksmart-doc:torna-restButton;

Next in Torna, we can see the relevant interface documentation, very convenient!

conclusion

When a tool becomes more popular, but some functional requirements are not met, there are often some enhancement tools, Torna for Swagger is such a tool. Torna document interface and debugging functions are obviously much higher than Swagger, but also increased the authority management function, document security greatly enhanced, we feel good if you can try it!

The resources

Official document: torna.cn/

Project source code address

Github.com/macrozheng/…

In this paper, making github.com/macrozheng/… Already included, welcome everyone Star!