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

博主：本当迷
发布时间：2023 年 03 月 03 日
46 次浏览
暂无评论
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 日

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

发表评论取消回复

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

梦一帆
不错，强
小孙同学
站名: 小孙同学链接: https://blog.sunguo...
linkkk
我好像没找到编辑器的选项欸
梦一帆
Handsome封装的OωO
梦一帆
认真看了下感觉不错，探花里面还有一个阿里云oss上传案例，识别...

再见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无侵入生成接口文档

发表评论取消回复

【修仙之路】JAVA学习路线

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

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

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

利用阿里云盘实现电脑内存扩大

【JAVA】单例设计模式

C语言-if实现从大到小排序

SpringAMQP

C语言-加'0'与减'0'的区别

推荐一款压缩软件Bandizip

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

发表评论 取消回复

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

发表评论取消回复