Torna

# 生成文档（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官方插件推送

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

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

最新版本：maven

在 src/main/resources 目录下创建 torna.yml 配置文件

# Torna 插件配置

# Torna 推送地址
url: http://localhost:7700/api
# Torna 推送 token
token: "xx"
# 推送人，如果为空，则获取当前电脑用户名
author: ""

# 扫描配置，可配置多个
## 前缀说明：
## 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"
  # # 扫描目录下所有接口
  # - "path:/Users/thc/Projects/torna-plugin/src/test/java/cn/torna/plugin/test/controller/goods"
# 调试模式，true：打印推送内容
debug: false

配置对应关系

img

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

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
}

参数说明:

  • outPath：固定填这个不用变
  • projectName：项目名称
  • packageFilters：Controller接口对应的package目录，多个用,隔开
  • openUrl：Torna中的OpenAPI接口
  • appToken：Torna中的OpenAPI token
  • debugEnvName：Torna中调试环境名称
  • debugEnvUrl：Torna中调试环境地址
  • tornaDebug：是否开启调试，初次使用建议开启，后面稳定了关闭
  • replace：是否替换文档，建议true
  • showValidation：显示校验信息，建议false

对应关系如下图所示：

在项目根目录输入maven命令：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

推送成功后，前往Torna查看文档是否生成

# 多模块推送

如果项目是多模块应用

项目根pom.xml配置smart-doc插件

模块A中resources下添加smart-doc.json，一般这个模块是启动模块，如果有多个启动模块，需要加多个smart-doc.json

项目根目录输入maven命令：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :模块A -am

会把模块A中的接口推送到Torna

示例工程 (opens new window)

← Torna插件 →