Torna：接口文档解决方案，目标是让接口文档管理变得更加方便、快捷

Torna

接口文档解决方案，目标是让接口文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护接口文档，将不同形式的文档纳入进来统一维护。

Torna弥补了传统文档生成工具（如swagger）的不如之处，在保持原有功能的前提下丰富并增强了一些实用的功能。

Torna官网

解决文档管理痛点

• 不满足swagger文档预览页面和调试页面的展现方式
• 不喜欢swagger这种侵入式注解
• 希望使用javadoc注释生成文档，并进行接口调试
• 希望把公司所有项目接口文档进行统一管理
• 希望把项目中的若干文档提供给第三方调用者查看
• 希望可以统一管理项目中的字典枚举

如果您有以上几个需求和痛点，或许可以尝试一下使用Torna

快速部署

准备工作

Java环境，最低要求Java8
MySQL，要求5.6.5+

前往 发行版页面 ，下载最新版本，解压zip

导入数据库，执行mysql.sql

打开application.properties配置文件，修改数据库连接配置

执行sh startup.sh启动（Windows执行startup.bat）

访问：http://ip:7700

登录账号：
用户名：admin，密码：123456

生成文档

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

/**
 * 产品模块
 *
 * @author thc
 */
@RestController
@RequestMapping("shop/product")
public class ProductController {

    /**
     * 查询产品
     *
     * @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 aa
     */
    private String productNo;

    /**
     * 备注
     *
     * @mock xxx
     */
    private String remark;

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

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

下面通过一个springboot工程讲解如何使用：

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

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

到此Torna这边配置完毕

创建一个springboot工程，然后改成多模块形式，最终得到如下目录结构：

torna-and-smart-doc  # 项目根目录 
├──shop-common       # 公共模块
├──shop-web          # 接口模块(springboot启动模块)
├──pom.xml           # 根pom文件
└──readme.md

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

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

在shop-web中的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
}

参数说明:

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

对应关系如下图所示：

到此smart-doc配置完毕，接下来推送文档到Torna

在项目根目录输入maven命令：

mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :shop-web -am

其中-pl :shop-web -am表示推送哪个子模块

推送成功后前往Torna接口列表查看文档

示例项目

Torna官网