接口文档解决方案,目标是让接口文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护接口文档,将不同形式的文档纳入进来统一维护。
Torna弥补了传统文档生成工具(如swagger)的不如之处,在保持原有功能的前提下丰富并增强了一些实用的功能。
如果您有以上几个需求和痛点,或许可以尝试一下使用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平台预览效果如下图所示:
在Torna中新建一个项目,进入项目创建一个模块,输入模块名称
到此Torna这边配置完毕
创建一个springboot工程,然后改成多模块形式,最终得到如下目录结构:
torna-and-smart-doc # 项目根目录
├──shop-common # 公共模块
├──shop-web # 接口模块(springboot启动模块)
├──pom.xml # 根pom文件
└──readme.md
在项目根pom.xml中添加smart-doc插件
<plugins>
<plugin>
<groupId>com.github.shalousungroupId>
<artifactId>smart-doc-maven-pluginartifactId>
<version>2.4.9version>
<configuration>
<configFile>${basedir}/src/main/resources/smart-doc.jsonconfigFile>
<projectName>商城项目projectName>
configuration>
<executions>
<execution>
<phase>packagephase>
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
}
参数说明:
对应关系如下图所示:
到此smart-doc配置完毕,接下来推送文档到Torna
在项目根目录输入maven命令:
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :shop-web -am
其中-pl :shop-web -am
表示推送哪个子模块
推送成功后前往Torna接口列表查看文档
示例项目
Torna官网