When swagger met Torna, he was tall in an instant!

Swagger is a very popular API document generation tool. I believe many guys are using it! If you use it too much, you may feel that its interface is ugly and its function is weak. Today, I recommend a tool Torna, which can be used with swagger to build a beautiful and powerful API document website. I hope it will be helpful to you!

Springboot e-commerce project Mall (50K + star) address: https://github.com/macrozheng/mall

Introduction to Torna

Torna is an enterprise level interface document solution that can be used with swagger. It has the following functions:

• Document management: support interface document addition, deletion, modification and query, interface debugging, dictionary management, import and export functions;
• Permission management: it supports the permission management of interface documents, and has three roles: visitor, developer and administrator;
• Dual mode: original dual mode,management model Can be used to edit document content,Browse modePurely consult the document, and there is no interference of other elements in the interface.

Torna project architecture

Torna is a front-end and back-end separation project. The back-end uses springboot + mybatis and the front-end uses Vue + elementui. The technology stack is very mainstream! It can not only build API document websites, but also a very good learning project. Let’s take a look at its project architecture first.

• First, we need to download the source code of Torna. Download address: https://gitee.com/durcframewo…

• After the download is successful, import the code into the idea, and the project structure is as follows;

• Let’s take another lookserverModule structure, a very standard springboot project;

• Look againfrontModule structure, a very standard Vue project, is worth learning!

install

Next, let’s run Torna and experience its functions. There are two installation methods: windows and Linux.

Windows

Let’s introduce the installation method of Torna under windows. If you want to learn more about Torna, you can use this method.

Back end operation

• First create a databasetorna, and then import the in the projectmysql.sqlScript. After successful import, the table structure is as follows;

• Modify the project’s configuration fileserver/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

• Then run the project startup classTornaApplicationThe console prints the following information to indicate successful startup.

Front end operation

• Enter the front-end project directoryfront, runningnpm installCommand installation dependency;

• At this point, if you encounternode-sassIn case of failure to install, you can directly use the following commands to install;

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

• After the dependency installation is completed, you cannpm run devCommand to start the project. After successful startup, access the address: http://localhost:9530/

• Through experience account password[email protected]:123456You can access the Torna service, and the interface is still good!

Linux

Using docker to install Torna under Linux is very simple. If you only want to use Torna as API document service, you can use this method.

• First, we need to download the docker image of Torna;

docker pull tanghc2020/torna:latest

• When the download is complete, the configuration file will beapplication.propertiesCopy profile to/mydata/torna/configDirectory and 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

• Then run the Torna service through the following command;

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

• Since the front-end and back-end items are directly included in the image, they can be used directly. Access address: http://192.168.3.101:7700

use

Torna supports importing interface documents from a variety of tools, including swagger, smart doc, OpenAPI, postman, etc. next, let’s experience its functions!

Use with swagger

Torna can greatly enhance the function of swagger, and the interface is beautiful enough. Let’s experience it!

• Before using, we need to configure in Torna. First, we configure an open user and create a new onemacroYour account, rememberAppKeyandSecret；

• Then create a projectmall-tiny-trona；

• Next, create a module and open itOpenAPITags, gettingRequest pathandtoken；

• After that, the Torna plug-in is integrated into the project using swagger. It is very simple to add the following dependencies;

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

• Then inresourcesAdd configuration file under directorytorna.json, refer to the notes for configuration description;

{
  //Start push
  "enable": true,
  //Scan package, multiple; separate
  "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: environment name, debugging path, multiple separated by "|"
  "debugEnv": "test,http://localhost:8088",
  //Pusher
  "author": "macro",
  //Open debugging: true / false
  "debug": true,
  //Replace document, true: replace, false: do not replace (append). Default: true
  "isReplace": true
}

• Next, by callingSwaggerPluginofpushDocMethod to push the interface document to Torna;

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

    @Test
    public void pushDoc(){
        //Push the document to the Torna service. By default, you can find the torna json
        SwaggerPlugin.pushDoc();
    }

}

• After successful push, the following interface information will be displayed in the interface list;

• Check the details of the interface. It’s still very comprehensive. The interface is also good!

• After running our project, you can directly debug the interface on it. Call the login interface to try;

• If we want to set the public request header, for example, for login authenticationAuthorizationHead, you canModule configurationConfiguration in;

• Before the back-end interface is completed, if we need mock data, we can use the mock function;

• Here we mock the login interface. Of course, you can also use mock script. As long as the interface is defined, the front end can use mock’s data joint debugging.

Use with smart doc

Smart doc is an annotation free API document generation tool. For specific use, please refer to the smart doc tutorial. Here is a description of its combination with Torna.

• Modify firstmall-tiny-smart-docSmart doc configuration file for the projectsmart-doc.json, add the following configuration about Torna;

{
  //Torna platform docking appkey
  "appKey": "20211103905498418195988480",
  //Torna platform apptoken
  "appToken": "b6c50f442eb348f48867d85f4ef2eaea",
  //Torna platform secret
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  //Torna platform address, fill in your own privatization deployment address
  "openUrl": "http://localhost:7700/api",
  //Test project interface environment
  "Debugenvname": "test environment",
  //Test project interface address
  "debugEnvUrl":"http://localhost:8088"
}

• Since the Maven plug-in of smart doc already has the function of pushing documents to Torna, we just need to double-clicksmart-doc:torna-restPush button;

• Next, in Torna, we can see the relevant interface documents, which is very convenient!

summary

When a tool becomes more and more popular, but some functional requirements can not be met, some enhancement tools are often produced. Torna is such a tool for swagger. Torna’s document interface and debugging function are significantly higher than swagger’s, and it also adds the permission management function, which greatly enhances the security of documents. If you think it’s good, you can try it!

reference material

Official documents: http://torna.cn/

Project source code address

https://github.com/macrozheng…

This article GitHub https://github.com/macrozheng/mall-learning Already included, welcome to star!