# 生成文档（SpringBoot）

这里以SpringBoot项目为例，介绍如何把接口文档推送到Torna

比如有一个接口定义如下：


/**
 * 产品模块（文件夹名称）
 *
 * @author thc（维护人）
 */
@RestController
@RequestMapping("shop/product")
public class ProductController {

    /**
     * 查询产品（文档标题）
     * @apiNote 【选填】文档详细描述，吧啦吧啦
     * @param productNo 产品id|123
     * @return
     */
    @GetMapping
    public Result<ProductVO> get(@RequestParam Integer productNo) {
        ProductVO productVO = new ProductVO();
        productVO.setProductNo(String.valueOf(productNo));
        return Result.ok(productVO);
    }

}

ProductVO类：

public class ProductVO {
    /**
     * 产品id
     *
     * @mock 示例值1
     */
    private String productNo;

    /**
     * 备注
     *
     * @mock 示例值122
     */
    private String remark;

    /**
     * 产品详情
     *
     * @mock 示例值133
     */
    private ProductDetailVO productDetailVO;
    
    ... 省略getter setter   
}

然后通过一条推送命令即可把文档信息推送到Torna平台，前往Torna平台预览效果如下图所示：

具体步骤如下：

在Torna中新建一个项目，进入项目创建一个模块，输入模块名称

点击OpenAPI，可以看到请求接口和token

到此Torna这边配置完毕

# 使用Torna官方插件推送

# 功能特性

支持springmvc接口推送
支持dubbo接口推送
支持swagger注解推送
支持接口分类管理
支持配置文件继承
支持第三方jar源码扫描
支持重写第三方jar包类的字段描述和示列
支持隐藏第三方jar包类的字段
支持接口/字段隐藏
全局定义默认示例值
全局定义枚举字段code
支持重写通用返回类(Result<T>)描述/示例值
支持枚举描述国际化
支持cli方式推送

准备工作

部署Torna
安装maven并配置环境变量（执行mvn -v成功即可）

在项目根目录下创建 torna.yml 配置文件

# Torna 推送地址
url: http://localhost:7700/api
# Torna 推送 token
token: "xx"

# 调试模式，true：打印推送内容
debug: true

如果使用swagger申明文档，添加一行配置：

useSwagger: true

配置对应关系

# 推送文档

方式1【推荐】：使用IDEA插件推送，支持swagger注解（内测中）

支持IDEA版本：2023.3及以后

IDEA搜索插件Torna进行安装

如何使用：右键Java文件或包名

方式1：右键Java文件点击 Push Doc（推送类中所有接口）
方式2：右键包名 Push Doc（推送包下所有接口）
方式3：打开Java文件，类名处右键 Push Doc（推送类中所有接口）
方式4：打开Java文件，接口方法名处右键 Push Doc（推送当前接口）

方式2：cli命令推送

前提条件

本地安装 Java8 或更高版本
本地安装 unzip 命令
本地安装 curl 或 wget 命令

下载cli脚本torna-cli.sh (opens new window)

或者使用wget下载

wget https://gitee.com/durcframework/torna-cli/blob/main/shell/torna-cli.sh

添加执行权限：chmod +x torna-cli.sh

执行查看帮助

./torna-cli.sh -h

执行推送命令：

sh torna-cli.sh \    
-u http://localhost:7700/api \
-t 03de04f2104d41a2b6ced3c4afb22627 \
-s /Users/thc/Projects/torna-example/torna-and-smart-doc \
-f "class:cn.torna.example.web.controller.product.CategoryController" \
-a jim1 \
-d

指定配置文件

sh torna-cli.sh \    
-c /Xx/xx/torna.yml \
-s /Users/thc/Projects/torna-example/torna-and-smart-doc \
-f "class:cn.torna.example.web.controller.product.CategoryController" \
-a jim1 \
-d

# 参数说明

参数	简写	说明	是否必填
--src	-s	源代码目录，多个目录用逗号分隔	是
--configFile	-c	配置文件路径	否
--url	-u	Torna 平台地址	否
--token	-t	Torna 平台 token	否
--author	-a	作者名称	否
--debug	-d	调试模式	否
--help	-h	显示帮助信息	否
--version	-V	显示版本信息	否
--file	-f	配置文件内容	否

方式3：运行代码推送

在项目启动模块新增maven依赖：

<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>torna-plugin</artifactId>
    <version>版本号</version>
    <scope>test</scope>
</dependency>

最新版本： maven

yml添加配置

# 扫描配置，可配置多个
## 前缀说明：
## package: 扫描包
## class: 扫描类，类全名
## method: 扫描方法，格式：类全名#方法名
## path: 扫描目录
scans: 
  # 扫描包下所有接口
  - "package:cn.torna.plugin.test.controller"
  # 扫描文件下所有接口
  # - "class:cn.torna.plugin.test.controller.UserController"
  # # 扫描单个接口
  # - "method:cn.torna.plugin.test.controller.UserController#postPage3"

在单元测试中调用以下方法：

import cn.torna.plugin.core.TornaPlugin;

public class PushDoc {
    public static void main(String[] args) {
        // 自动查找 classpath 下的 torna.yml 并推送
        TornaPlugin.pushDoc();
        // 或指定文件
        // TornaPlugin.pushDoc("torna-1.yml");
    }
}

代码运行后，可将本地接口文档推送到Torna平台

插件更多用法，可参考文档：Torna插件

# 使用smart-doc插件推送

在项目根pom.xml中添加smart-doc插件

<plugins>
    <!-- smart-doc插件 
        https://gitee.com/TongchengOpenSource/smart-doc
    -->
    <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>3.0.3</version>
        <configuration>
            <!--指定生成文档的使用的配置文件-->
            <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
            <!--指定项目名称-->
            <projectName>商城项目</projectName>
        </configuration>
        <executions>
            <execution>
                <phase>package</phase>
            </execution>
        </executions>
    </plugin>
</plugins>

在resources下添加一个smart-doc.json文件，内容如下：

{
  "outPath": "target/doc",
  "projectName": "商城项目",
  "packageFilters": "cn.torna.example.web.controller.*",
  "openUrl": "http://localhost:7700/api",
  "appToken": "7d58c03fee554abc929b4cb2ad76feeb",
  "debugEnvName":"本地环境",
  "debugEnvUrl":"http://127.0.0.1:8080",
  "tornaDebug": true,
  "replace": true,
  "showValidation": false
}