再见Swagger！拥抱smart-doc无侵入生成接口文档

博主：本当迷
发布时间：2023 年 03 月 03 日
633 次浏览
4 条评论
4249字数
分类： java

## 使用smart-doc：

<div class="inner-content" >
<p class="inser-title">接口文档生成工具smart-doc</p>
<div class="inster-summary text-muted">
一简介：smart-doc是一款接口文档生成工具，它完全是根据接口源码进行分析生成接口文档，不会使用任何注解侵入业...
</div>
</div>
</a>

</div>

</div>

## 前言：

我们介绍了smart-doc的使用。大老板看到后很激动，smart-doc这么好用，所有项目必须马上安排呀。

Two hours later，前端工程师炸了：“接口改了？我怎么不知道！！！写了半天，白写了！！！为什么不把新的接口文档发给我？Why?”

后端工程师麻了：“我这接口一天改八百遍，总不能一直生成文档，群发文档吧。”

那......前端与后端之间的矛盾如何调和呢？这就需要一个新的工具来负责调和前后端啦。

## Torna

### **一. Torna介绍**

smart-doc虽然使用简单，但在进行接口测试时，如果每次都单独导出接口又档，再进行测试，
显然相对麻烦。尤其是多人针对同一个项目的接口讲行测试时，显得更加不便。

我们不仅有smart-doc，我们还有Torna。Torna在手，天下我有！

![](https://www.bdmcom.cn/usr/uploads/2023/03/2389981701.png)

本文会通过smart-doc + Torna实现文档全流程自动化，使用smart-doc无侵入，完成Java源代码和注释提取生成API文档，**自动将文档推送到Torna企业级接口文档管理平台。**

通过这套组合，我们只需要写完Java注释，就能把接口信息推送到Torna平台，从而实现接口预览、接口调试。

![](https://www.bdmcom.cn/usr/uploads/2023/03/714951365.png)

**官方文档：** https://torna.cn/

### **二. Torna环境安装部署**

#### **1.Torna项目简介**

Torna后台基于SpringBoot进行开发，前端使用Vue，同时借助mysql进行数据管理。Torna真的非常贴心，在源码中，还为我们提供了docker部署或docker-compose部署时需要的所有配置文件，真的是保姆级的源码。

**源码地址**：https://gitee.com/durcframework/torna

![](https://www.bdmcom.cn/usr/uploads/2023/03/4264074773.png)

### **2.部署前准备工作**

如果我们想部署Torna项目，需要准备如下环境：

> * 准备好一台Linux服务器；
> * 安装好docker相关环境；
> * 下载源码，将torna-docker-compose拷贝到服务器某个目录下。

### **3. 通过docke-composer部署环境**

#### **3.1 torna-docker-compose目录结构**

![](https://www.bdmcom.cn/usr/uploads/2023/03/1439758375.png)

> application.properties：Torna应用的端口号，mysql数据库的用户名密码等信息；
>
> docker-compose.yml：mysql和torna镜像的信息；
>
> DockerFile：根据mysql镜像构建新的镜像的配置信息；
>
> my.cnf：mysql配置信息；
>
> mysql.sql：Torna应用的数据库表相关的sql语句

#### **3.2 修改docker-compose.yml文件**

对docker-compose.yml文件进行修改，取消指定位置的注释。另外，也可以根据实际情况，修改mysql容器的映射端口号。

docker-compose.yml最终配置如下所示，读者也可以根据实际需求进行修改。

```yaml
version: "3"
services:
  mysql:
    build:
      context: ./
      dockerfile: Dockerfile
    container_name: mysql
    ports:
      - 3306:3306
    environment:
      TZ: Asia/Shanghai
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_ROOT_HOST: '%'
    command:
      --default-authentication-plugin=mysql_native_password
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_general_ci
      --lower_case_table_names=1
    volumes:
      - ./my.cnf:/etc/my.cnf
    networks:
      - torna-net
    restart: always
  torna:
    image: tanghc2020/torna:latest
    container_name: torna
    ports:
      - 7700:7700
    depends_on:
      - mysql
    ## 建立连接
    links:
      - mysql
    volumes:
      - ./application.properties:/torna/config/application.properties
    environment:
      - TZ=Asia/Shanghai
      - JAVA_OPTS=-server -Xmx512m -Xms512m -Djava.awt.headless=true
    networks:
      - torna-net
    restart: always
networks:
  torna-net:
```

### **4.部署环境**

切换到docker-compose.yml所在目录，执行如下命令：

```xmd
docker-compose up -d
```

### **5.访问Torna**

访问路径：http://ip:7700

### **6.smart-doc推送到Torna**

同志们，激动人心的时刻到了！下面就开始通过smart-doc推送文档到torna的处理。

#### **6.1 查看应用的OpenApi**

在SpringBoot项目中，我们会用到其中的路径和token。

![](https://www.bdmcom.cn/usr/uploads/2023/03/291944462.png)

### **7 修改smart-doc.json**

这里我们主要增加如下配置：

> "appToken"：Torna平台appToken，从上文提到的OpeonApi中查找。这个配置很重要，可以不要填错呦！"openUrl"：Torna平台提供的请求路径地址，也可以直接查找到
> "debugEnvName"：Torna测试环境名称
> "debugEnvUrl"：测试的接口所在的服务器的url
> "replace"：推送Torna时，是否替换旧的文档

```json
{
  "serverUrl": "http://localhost:8080",
  "pathPrefix": "",
  "allInOne": true,
  "outPath": "D://md2",
  "style": "xt256",
  "createDebugPage": false,
  "appToken": "0ccc4676682a4bb8802d221c8eac37fd", // torna平台appToken
  "openUrl": "http://192.168.17.101:7700/api",    // torna平台地址，填写自己的私有化部署地址
  "debugEnvName":"测试环境",                       // torna测试环境名称
  "debugEnvUrl":"http://192.168.17.1:8080",       // 接口所在的测试服务器的url
  "replace": true,                                // 推送torna时替换旧的文档
  "revisionLogs": [
    {
      "version": "1.0",
      "revisionTime": "2023-01-31 10:30",
      "status": "创建",
      "author": "renr",
      "remarks": "初始创建"
    }
  ]
}
```

### **8 通过idea推送接口**

操作超级方便，双击“smart-doc:torna-rest”即可

![](https://www.bdmcom.cn/usr/uploads/2023/03/3192446295.png)

## 9 查看推送的接口

在Torna中刷新页面，即可看到接口信息。怎么样？so easy吧。

![](https://www.bdmcom.cn/usr/uploads/2023/03/1822053097.png)

最后修改：2023 年 03 月 03 日

如果文章有用，请随意打赏。

4 条评论

流量卡大全 Google Chrome 98.0.4758.139 Windows 7
October 1st, 2023 at 09:18 pm

你好，看完你的博客文章，感觉很不错！希望与你网站首页友情链接
流量卡
http://53go.cn/
专注于移动/联通/电信推出的大流量多语音活动长短期套餐手机卡的相关知识的介绍普及
听说互换友情链接可以增加网站的收录量，特此来换，如果同意的话就给internetyewu@163.com发信息或者就在此回复下吧！

回复
王光卫博客 Google Chrome 114.0.0.0 Mac OS X Lion 10.15.7
June 6th, 2023 at 01:02 pm

以前没接触，现在多了点知识

回复
潜心学习的匿名人士 Firefox 113.0 Windows 10
May 23rd, 2023 at 01:30 pm

整个博客项目是你自己从零开始搭起来的吗？不错啊年轻有为赞一个(/ω＼)

回复
芋泥苑 Firefox 108.0 Windows 7
April 29th, 2023 at 08:21 pm

你写得非常清晰明了，让我很容易理解你的观点。

回复

发表评论取消回复

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

流量卡大全
你好，看完你的博客文章，感觉很不错！希望与你网站首页友情链接流...
免费节点
感谢博主精彩分享，辛苦了
免费节点
感谢分享
DragonJay
域名换成blog.dragonjay.top力，当然也可以改为...
王光卫博客
以前没接触，现在多了点知识

再见Swagger！拥抱smart-doc无侵入生成接口文档

本当迷 • 2023 年 03 月 03 日

## 使用smart-doc：

## 前言：

我们介绍了smart-doc的使用。大老板看到后很激动，smart-doc这么好用，所有项目必须马上安排呀。

Two hours later，前端工程师炸了：“接口改了？我怎么不知道！！！写了半天，白写了！！！为什么不把新的接口文档发给我？Why?”

后端工程师麻了：“我这接口一天改八百遍，总不能一直生成文档，群发文档吧。”

那......前端与后端之间的矛盾如何调和呢？这就需要一个新的工具来负责调和前后端啦。

## Torna

### **一. Torna介绍**

我们不仅有smart-doc，我们还有Torna。Torna在手，天下我有！

![](https://www.bdmcom.cn/usr/uploads/2023/03/2389981701.png)

通过这套组合，我们只需要写完Java注释，就能把接口信息推送到Torna平台，从而实现接口预览、接口调试。

![](https://www.bdmcom.cn/usr/uploads/2023/03/714951365.png)

**官方文档：** https://torna.cn/

### **二. Torna环境安装部署**

#### **1.Torna项目简介**

**源码地址**：https://gitee.com/durcframework/torna

![](https://www.bdmcom.cn/usr/uploads/2023/03/4264074773.png)

### **2.部署前准备工作**

如果我们想部署Torna项目，需要准备如下环境：

> * 准备好一台Linux服务器；
> * 安装好docker相关环境；
> * 下载源码，将torna-docker-compose拷贝到服务器某个目录下。

### **3. 通过docke-composer部署环境**

#### **3.1 torna-docker-compose目录结构**

![](https://www.bdmcom.cn/usr/uploads/2023/03/1439758375.png)

#### **3.2 修改docker-compose.yml文件**

对docker-compose.yml文件进行修改，取消指定位置的注释。另外，也可以根据实际情况，修改mysql容器的映射端口号。

docker-compose.yml最终配置如下所示，读者也可以根据实际需求进行修改。

### **4.部署环境**

切换到docker-compose.yml所在目录，执行如下命令：

```xmd
docker-compose up -d
```

### **5.访问Torna**

访问路径：http://ip:7700

### **6.smart-doc推送到Torna**

同志们，激动人心的时刻到了！下面就开始通过smart-doc推送文档到torna的处理。

#### **6.1 查看应用的OpenApi**

在SpringBoot项目中，我们会用到其中的路径和token。

![](https://www.bdmcom.cn/usr/uploads/2023/03/291944462.png)

### **7 修改smart-doc.json**

这里我们主要增加如下配置：

### **8 通过idea推送接口**

操作超级方便，双击“smart-doc:torna-rest”即可

![](https://www.bdmcom.cn/usr/uploads/2023/03/3192446295.png)

## 9 查看推送的接口

在Torna中刷新页面，即可看到接口信息。怎么样？so easy吧。

![](https://www.bdmcom.cn/usr/uploads/2023/03/1822053097.png)

再见Swagger！拥抱smart-doc无侵入生成接口文档

4 条评论

发表评论取消回复

【修仙之路】JAVA学习路线

对于异或运算的初步认识与auto用法

【JAVA经典例题】生产者/消费者问题

最近某音挺火的代码实现爱心形状

再见Swagger！拥抱smart-doc无侵入生成接口文档

Eureka注册中心之搭建eureka-server和eureka-client

ps-油漆桶工具

【java】springboot入门核心配置

【java】创建bean的4中方法

【matlab】矩阵的相关操作及运算

再见Swagger！拥抱smart-doc无侵入生成接口文档

4 条评论

发表评论 取消回复

再见Swagger！拥抱smart-doc无侵入生成接口文档

发表评论取消回复