# torna-plugin

**Repository Path**: durcframework/torna-plugin

## Basic Information

- **Project Name**: torna-plugin
- **Description**: Torna官方接口文档插件，该插件通过扫描 Java 源代码和 Spring MVC 注解，自动生成标准化接口文档并推送到 Torna 平台。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Torna 接口文档插件

该插件通过扫描 Java 源代码和 Spring MVC 注解，自动生成标准化接口文档并推送到 Torna 平台。

## 功能特性

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


## 1. 使用方式

### 1.1 引入依赖

在项目的启动模块 `pom.xml` 中引入依赖

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

最新版本：<img alt="maven" src="https://img.shields.io/maven-central/v/cn.torna/torna-plugin">

### 1.2 添加配置文件

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

```yaml
# 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
```

完整配置内容见：[默认配置](./torna.default.yml)

### 1.3 执行推送

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

```java
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");
    }
}
```

## 2. Tag 使用说明

### 2.1 类级别
*   **@category**: 指定文档目录，支持多级（使用`/`隔开，如 `@category 模块/子模块`）。若不指定，默认使用类注释。
*   **@author**: 模块作者。
*   **@hidden 或 @ignore**: 忽略该 Controller 下的所有接口。
*   **@enum.code**: 指定枚举值字段，如：`@enum.code type`
*   **@dubbo**: 指定当前接口dubbo服务

示列代码：

```java
/**
 * User Management
 * 
 * @category 一级/二级
 * @author jim
 */
@RestController
@RequestMapping("/user")
public class UserController {}

// 指定枚举值字段
/**
 * 是/否枚举
 * 
 * @enum.code value
 */
@AllArgsConstructor
@Getter
public enum YesOrNoEnum {
    /**
     * 是-yes
     */
    YES(1, "是"),
    /**
     * 否-no
     */
    NO(0, "否");
    private Integer value;
    private String desc;
}
```

### 2.2 方法级别 (Method)
*   **@author**: 接口作者（优先于类级别）。
*   **@apiNote**: 接口详细描述。
*   **@version 或 @since**: 指定接口版本号。
*   **@deprecated**: 标记接口已废弃及废弃原因。
*   **@hidden 或 @ignore**: 忽略该接口。
*   **@response.字段名**: 重写返回对象的字段描述和示例值，格式：`@response.字段名 描述信息|示例值`。
*   **@codes**: 指定错误码，格式：`code:描述:解决方案|code:描述`。
*   **@param**: 参数描述，格式：`@param 参数名  描述|示例值`
*   **@return**: 定义单值返回的描述个示例值，格式：`@return 描述|示例值`

示列代码：

```java
/**
 * Get user by ID
 * 
 * @param id    User ID|123
 * @param name  User name | jim
 * @param token Token|xxxxx
 * @return User info
 * @author tanghc
 * @apiNote This is a note for the API
 */
@GetMapping("/get/{name}")
public Result<UserDTO> getUser(@RequestParam @NotNull Long id, @PathVariable String name,
        @RequestHeader String token) {
    return Result.success(new UserDTO());
}

/**
 * 单值返回
 * 
 * @param id   User ID|123
 * @param name User name|jim
 * @return return user name...|xxxx
 * @author tanghc
 * @apiNote This is a note for the API
 * @deprecated This API is deprecated
 */
@GetMapping("/get1/{name}")
public String getUser1(@RequestParam @NotNull Long id) {
    return "success";
}

/**
 * 重写Result中的字段描述和示例值；指定错误码
 * 
 * @param userDTO User data
 * 
 * @response.data this is a response data|xxxxxxx
 * @response.code 200 is success|200
 * @response.message message|success
 * @codes 200:success|300:用户姓名格式错误:请输入正确的姓名
 * @apiNode: Batch create user.
 * @return Success status
 */
@PostMapping("/createBatch")
public Result<String> createBatch(@RequestBody List<UserDTO> userDTO) {
    return Result.success("success");
}
```

### 2.3 参数/字段级别 (Field/Param)
*   **@required**: 标记参数必填（支持 JSR-303 注解如 `@NotNull`）。
*   **@mock 或 @example**: 指定参数示例值。
*   **@enum**: 标记字段为枚举并指定枚举类，格式：`@enum {EnumClass}`。
*   **@hidden 或 @ignore**: 忽略该字段。

示列代码：

```java
public class UserDTO {
    /**
     * User ID
     * @mock 1
     */
    private Long id;
    /**
     * User name
     * @example jim
     */
    @NotBlank
    @Length(max = 20)
    private String username;
    /**
     * User age
     * @required
     */
    private Integer age;
    /**
     * User gender
     * @enum {GenderEnum}
     * @example 1
     */
    private Integer gender;
}
```

## 3. 配置文件说明 (`torna.yml`)

| 属性 | 描述 | 默认值 |
| :--- | :--- | :--- |
| `parent` | 继承父级配置 | - |
| `url` | Torna 推送地址 | - |
| `token` | Torna 项目推送 token | - |
| `author` | 默认文档作者 | - |
| `debug` | 是否开启调试模式 | `false` |
| `showRawType` | 是否显示 Java 原始类型（如 `List<UserDTO>`） | `false` |
|`showArrayElementType`|如果为true：则数组类型显示 `array<string>`、`array<int32>` 等, 如果为false：则数组类型显示 `array`|true|
| `enumCodeName` | 枚举中代表值的字段名 | `code` |
| `enumDescName` | 枚举中代表描述的字段名 | `desc` |
| `scans` | 扫描配置列表，支持以下前缀：<br> - `package:` 扫描包<br> - `class:` 扫描类<br> - `method:` 扫描方法<br> - `file:` 扫描物理路径 | - |
| `thirdJar` | 第三方jar管理 | - |
|   └ `dependencies` | 定义依赖，格式：`<groupId>:<artifactId>[:version]`，版本号可选，不填则使用最新版本 | `com.xxx:demo` |
|   └ `jarClass` | 重写jar包类的字段描述和示列 | - |
|`category`| 定义分类排序 | - |
|`example`|示列值相关配置，具体见 [默认配置](./torna.default.yml)|-|
|`dubbo`|dubbo推送配置，具体见 [默认配置](./torna.default.yml) |-|

### 文档分类

在类注释中添加`@category <分类名称>[/<子目录>]`，多级目录用/隔开，如：`@category 订单中心/订单管理`

不同Controller可以填相同配置，文档推送是会进行整合

### 定义分类排序

设置`category`属性，格式：按 `分类名称` 排好即可，不需要填值。`分类名称`需要和接口上的 @category 注解值一致

```yaml
# 分类排序
category:
  订单中心:
    订单查询:
    结算管理:
  商品中心:
    商品查询:
    价格管理:
  Dubbo接口:
    商品接口:
    订单接口:
```

### 最佳实践

在团队开发过程中，大部分配置都是一样的，只有个别配置不同，比如扫描接口，因为每个人负责的模块不一样，扫描的接口也就不一样。

在这种情况下，可以定义一个公共的配置，然后每个人定义自己的配置，继承公共的配置即可。

假设公共配置文件是`torna.yml`，内容如下：

```yaml
# Torna 推送地址
url: http://localhost:7700/api
# Torna 推送 token
token: "xxxxx"
# 扫描方式交给子配置
# scans: 

# 调试模式，true：打印推送内容
debug: false
# 全局定义枚举code, desc字段名
enumCodeName: "code"
enumDescName: "desc"

# 第三方jar管理
thirdJar:
  # 定义依赖，格式：<groupId>:<artifactId>[:version]，版本号可选，不填则使用最新版本
  dependencies:
    - "com.baomidou:mybatis-plus-core"
    - "com.baomidou:mybatis-plus-extension"
```

然后建立子配置文件，可以用名字做后缀，如：`torna-xx.yml`

```yaml
# 继承父级配置，classpath下文件，如果父级文件在 resources/config/torna.yml 则填：parent: "config/torna.yml"
parent: "torna.yml"

# 推送人
author: "jim"

scans: 
  - "package:cn.torna.plugin.test.controller"
debug: true
```

执行推送

```java
public class PushDoc {
    public static void main(String[] args) {
         TornaPlugin.pushDoc("torna-xx.yml");
    }
}
```

## 本地调试

改个版本号，如：`0.1.3.1`，然后执行`mvn clean install -DskipTests`

本地依赖

```xml
<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>torna-plugin</artifactId>
    <version>0.1.3.1</version>
    <scope>test</scope>
</dependency>
```