Swagger作为一款十分风行的API文档生成工具，置信很多小伙们都在用！用多了可能会感觉它界面丑、性能弱。明天给大家举荐一款工具Torna，配合Swagger应用能够搭建界面丑陋、功能强大的API文档网站，心愿对大家有所帮忙！

SpringBoot实战电商我的项目mall（50k+star）地址：https://github.com/macrozheng/mall

Torna简介

Torna是一套企业级接口文档解决方案，能够配合Swagger应用。它具备如下性能：

  • 文档治理：反对接口文档增删改查、接口调试、字典治理及导入导出性能；
  • 权限治理：反对接口文档的权限治理，同时有访客、开发者、管理员三种角色；
  • 双模式：独创的双模式，管理模式能够用来编辑文档内容，浏览模式纯正查阅文档，界面无其它元素烦扰。

Torna我的项目架构

Torna是一个前后端拆散我的项目，后端应用SpringBoot+MyBatis来实现，前端应用Vue+ElementUI来实现，技术栈十分支流！它不仅能够搭建API文档网站，还是个十分好的学习我的项目，让咱们先来看看它的我的项目架构。
  • 首先咱们须要下载Torna的源码，下载地址：https://gitee.com/durcframewo...

  • 下载胜利后，将代码导入到IDEA中，我的项目构造如下；

  • 咱们再来看下server模块的构造，一个十分规范的SpringBoot我的项目；

  • 再来看下front模块的构造，一个十分规范的Vue我的项目，值得学习！

装置

接下来咱们把Torna运行起来，体验一下它的性能，这里提供Windows和Linux两种装置形式。

Windows

上面咱们来介绍Torna在Windows下的装置办法，如果你想深刻学习Torna的话能够采纳此种形式。

后端运行

  • 首先创立一个数据库torna，而后导入我的项目中的mysql.sql脚本，导入胜利后，表构造如下；

  • 批改我的项目的配置文件server/boot/src/main/resources/application.properties，批改对应的数据库连贯配置；
# Server portserver.port=7700# MySQL hostmysql.host=localhost:3306# Schema namemysql.schema=torna# Insure the account can run CREATE/ALTER sql.mysql.username=rootmysql.password=root
  • 而后运行我的项目启动类TornaApplication的main办法，控制台打印如下信息示意启动胜利。

前端运行

  • 进入前端我的项目目录front，运行npm install命令装置依赖；

  • 此时如果遇到node-sass无奈装置的状况，能够间接应用如下命令装置；
npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
  • 依赖装置实现后，能够通过npm run dev命令启动我的项目，启动胜利后拜访地址：http://localhost:9530/

  • 通过体验账号密码admin@torna.cn:123456能够拜访Torna服务，界面还是不错的！

Linux

在Linux下应用Docker装置Torna是非常简单的，如果你只想用Torna来做API文档服务的话能够采纳这种形式。
  • 首先咱们须要下载Torna的Docker镜像；
docker pull tanghc2020/torna:latest
  • 下载实现后将配置文件application.properties拷贝配置文件到/mydata/torna/config目录下，并批改数据库配置；
# Server portserver.port=7700# MySQL hostmysql.host=192.168.3.101:3306# Schema namemysql.schema=torna# Insure the account can run CREATE/ALTER sql.mysql.username=rootmysql.password=root
  • 而后通过如下命令运行Torna服务；
docker run -p 7700:7700 --name torna \-v /mydata/torna/config:/torna/config \-d tanghc2020/torna:latest
  • 因为镜像中间接蕴含了前端和后端我的项目，所以能够间接应用，拜访地址：http://192.168.3.101:7700

应用

Torna反对从多种工具导入接口文档，包含Swagger、smart-doc、OpenAPI、Postman等，接下来咱们来体验下它的性能！

联合Swagger应用

Torna能大大加强Swagger的性能，并且界面足够好看，上面咱们来体验下！
  • 在应用之前，咱们须要在Torna中进行配置才行，首先咱们来配置一个凋谢用户，新建一个macro的账号，记住AppKey和Secret；

  • 而后创立一个我的项目mall-tiny-trona；

  • 接下来创立一个模块，关上OpenAPI标签，获取申请门路和token；

  • 之后在应用Swagger的我的项目中集成Torna插件，非常简单，增加如下依赖即可；
<!-- Torna Swagger 插件 --><dependency>    <groupId>cn.torna</groupId>    <artifactId>swagger-plugin</artifactId>    <version>1.2.6</version>    <scope>test</scope></dependency>
  • 而后在resources目录下增加配置文件torna.json，配置阐明参考正文即可；
{  // 开启推送  "enable": true,  // 扫描package，多个用;隔开  "basePackage": "com.macro.mall.tiny.controller",  // 推送URL，IP端口对应Torna服务器  "url": "http://localhost:7700/api",  // appKey  "appKey": "20211103905498418195988480",  // secret  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",  // 模块token  "token": "74365d40038d4f648ae65a077d956836",  // 调试环境，格局：环境名称,调试门路，多个用"|"隔开  "debugEnv": "test,http://localhost:8088",  // 推送人  "author": "macro",  // 关上调试:true/false  "debug": true,  // 是否替换文档，true：替换，false：不替换（追加）。默认：true  "isReplace": true}
  • 接下来通过调用SwaggerPlugin的pushDoc办法来推送接口文档到Torna；
@RunWith(SpringRunner.class)@SpringBootTestpublic class MallTinyApplicationTests {    @Test    public void pushDoc(){        // 将文档推送到Torna服务中去，默认查找resources下的torna.json        SwaggerPlugin.pushDoc();    }}
  • 推送胜利后，在接口列表将显示如下接口信息；

  • 查看一下接口的详细信息，还是很全面的，界面也不错！

  • 把咱们的我的项目运行起来，就能够间接在下面进行接口调试了，调用下登录接口试试；

  • 如果咱们想设置公共申请头的话，比方用于登录认证的Authorization头，能够在模块配置中进行配置；

  • 在后端接口没有实现前，咱们如果须要Mock数据的话，能够应用Mock性能；

  • 这里咱们对登录接口进行了一下Mock，当然你也能够应用Mock脚本，这下只有接口定义好，前端就能够应用Mock的数据联调了。

联合smart-doc应用

smart-doc是一款无注解侵入的API文档生成工具，具体应用能够参考《smart-doc应用教程》 ，这里介绍下它与Torna联合应用。
  • 首先批改mall-tiny-smart-doc我的项目的smart-doc配置文件smart-doc.json，增加如下对于Torna的配置；
{  // torna平台对接appKey  "appKey": "20211103905498418195988480",  //torna平台appToken  "appToken": "b6c50f442eb348f48867d85f4ef2eaea",  //torna平台secret  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",  //torna平台地址，填写本人的私有化部署地址  "openUrl": "http://localhost:7700/api",  //测试项目接口环境  "debugEnvName":"测试环境",  //测试项目接口地址  "debugEnvUrl":"http://localhost:8088"}
  • 因为smart-doc的Maven插件曾经自带推送文档到Torna的性能，咱们只需双击smart-doc:torna-rest按钮即可；

  • 接下来在Torna中，咱们就能够看到相干的接口文档了，十分不便！

总结

当一种工具变得越来越风行，然而某些性能需要又满足不了时，往往会有一些加强工具产生，Torna对于Swagger来说正是这样一种工具。Torna的文档界面和调试性能显著比Swagger高大上多了，而且还减少了权限治理性能，文档的安全性大大加强，大家感觉不错的话能够尝试下它！

参考资料

官网文档：http://torna.cn/

我的项目源码地址

https://github.com/macrozheng...

本文 GitHub https://github.com/macrozheng/mall-learning 曾经收录，欢送大家Star！