乐趣区

关于java:当-Swagger-遇上-Torna瞬间高大上了

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 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
  • 而后运行我的项目启动类 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 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
  • 而后通过如下命令运行 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 的账号,记住 AppKeySecret

  • 而后创立一个我的项目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
}
  • 接下来通过调用 SwaggerPluginpushDoc办法来推送接口文档到 Torna;
@RunWith(SpringRunner.class)
@SpringBootTest
public 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!

退出移动版