# 生成文档(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.2</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)