生成文档（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这边配置完毕

在项目根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)