乐趣区

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

jiezi

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 的账号，记住 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)
@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！

退出移动版