# 生成文档(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
← 快速开始 Swagger文档推送 →