# Springdoc文档推送
使用条件:项目使用springdoc (opens new window)注解声明文档
Torna提供了springdoc推送插件,插件的作用是将本地项目中的springdoc文档内容推送到Torna平台,使用平台统一管理项目文档。
使用插件的好处有:
- 不用启动项目即可查看文档,调试接口
- 可区分多环境调试(开发环境、测试环境)
- 可定义第三方jar中没有写注解的类
示例工程 (opens new window) ,演示springdoc插件的用法
使用步骤:
点击
项目列表
,创建一个项目,进入项目,创建一个应用点击创建好的模块,切换到
OpenAPI
选项卡,得到url
,token
pom.xml添加依赖:
<dependency>
<groupId>cn.torna</groupId>
<artifactId>springdoc-plugin</artifactId>
<version>最新版本</version>
<scope>test</scope>
</dependency>
springdoc-plugin
最新版本:
src/main/resources
下添加一个torna.json
文件,内容如下:
{
// 开启推送
"enable": true,
// 扫描package,多个用;隔开
"basePackage": "cn.torna.tornaexample.controller",
// 推送URL,IP端口对应Torna服务器
"url": "http://localhost:7700/api",
// 模块token
"token": "931167d9347e4aec9409f2b275437431",
// 调试环境,格式:环境名称,调试路径,多个用"|"隔开
"debugEnv": "test,http://127.0.0.1:8088",
// 推送人
"author": "Jim",
// 打开调试:true/false
"debug": true,
// 是否替换文档,true:替换,false:不替换(追加)。默认:true
"isReplace": true
}
新增一个测试用例,内容如下:
/**
* 推送swagger文档
*/
public class DocPushTest {
/*
java9+需要添加VM参数:--add-opens java.base/java.lang.reflect=ALL-UNNAMED
java8不用添加
*/
public static void main(String[] args) {
SpringdocPlugin.pushDoc();
}
}
运行main方法,插件会自动把swagger文档推送到Torna服务器。
# 扫描特定的接口
如果只想推送某一个controller中的接口,或者只想推送某一个接口,可在配置文件中添加如下配置:
{
...
"scanApis": [
// 只推送UserController中的接口
"com.xxx.UserController"
],
...
}
scanApis是一个数组,可定义多个类,如果只想推送一个接口,填方法全名称即可:
{
...
"scanApis": [
// 只推送UserController中的接口
"com.xxx.UserController",
// 指定方法全名称,推送某一个接口
"com.xxx.OrderController.get"
],
...
}
以上配置会推送UserController中所有接口
+ OrderController.get接口
TIP
IDEA可以右键方法 -> Copy/Paste Special
-> Copy Reference
快速复制方法全名称
# 推送错误码
增加"codes": [{...}, {...}]
节点定义错误码,格式如下:
{
...
"codes": [
// 定义错误码
{
"name": "错误码", // 分组名称
"description": "这里是全局错误码", // 错误码描述
"itemType": "string", // 错误码类型
"items": [ // 错误码列表
{ "value": "W_10001", "description": "参数错误" },
{ "value": "W_10002", "description": "缺少token" },
{ "value": 10000, "type": "number", "description": "缺少参数" } // 单独指定类型
]
}
]
...
}
此外还可以定义枚举类型:
{
// 定义枚举
"codes": [
// 定义枚举
{
"name": "订单状态枚举",
"itemType": "number",
"items": [
{ "name": "WAIT_PAY", "value": 0, "description": "未支付" },
{ "name": "HAS_PAY", "value": 1, "description": "已支付" },
{ "name": "CANCEL", "value": 2, "description": "取消支付" }
]
},
]
}
codes节点全部参数如下:
{
"codes": [
{
"name": "枚举名称【必填】",
"description": "描述【可选】",
"itemType": "枚举类型【可选】",
"items": [ // 枚举项,必填
{ "name": "名称【可选】,不填使用value", "type": "类型【可选】,不填使用itemType", "value": "值【必填】", "description": "描述【可选】" }
]
}
]
}
# 第三方类处理
接口返回第三方类,但是没有写swagger注解,生成的文档没有描述、示例等信息,如mybatis-plus
中的Page<T>
类。
@Operation(summary = "第三方类演示")
@PostMapping("query")
public Result<Page<OrderDetail>> query(@RequestBody OrderQuery query) {
return Result.ok(new Page<>());
}
解决方法,在torna.json
文件中定义一个jarClass
节点,内容如下:
// 第三方jar中的class配置
"jarClass": {
// Page是第三方jar中的类,需要给类中的属性定义文档信息
"com.baomidou.mybatisplus.extension.plugins.pagination.Page": {
"records": { "value": "查询数据列表", "example": "" },
"total": { "value": "总数", "example": "100" },
"size": { "value": "页数", "example": "10" },
"current": { "value": "当前页", "example": "1" },
"countId": { "hidden": true },
"orders": { "hidden": true }
},
"com.xxx.common.Result": {
"code": { "value": "查询数据列表", "example": "100" },
"data": { "value": "数据", "example": "" },
"msg": { "value": "错误消息", "example": "xx" }
}
}
其中key
为第三方类的全限定名,value
是类中字段信息,各个属性值对应@ApiParam
中的属性,相当于给records
属性加了@ApiParam
注解。
# 多环境配置
默认查找resources下的torna.json
,可复制一份,命名为torna-test.json
,用来区分不同环境,然后参数传文件名称
SpringdocPlugin.pushDoc("torna-test.json");
# 指定object类型对象
在处理第三方json类时(如:com.alibaba.fastjson.JSONObject
、cn.hutool.json.JSONObject
)这些类中有具体的属性,
这些属性不应该显示出来,返回示例应该显示{}
(空对象)
因此需要对这些类做特殊处理,在torna.json
中新增如下节点进行配置:
"objectClassList": [
"cn.hutool.json.JSONObject",
"com.alibaba.fastjson.JSONObject"
]
配置完后,如果有这些类型的参数,返回示例都显示{}
# 注解扩展使用
使用@ApiOperation.extensions
的扩展属性用来配置其它信息
- 指定维护人
指定之后将会在文档页展示当前接口的维护人
@ApiOperation(value = "获取产品", notes = "获取产品说明。。", extensions = {
// 指定维护人,name固定为author
@Extension(name = "author", properties = {
// name:维护人姓名,value空,可以填一个或多个
@ExtensionProperty(name = "Tom", value = ""),
@ExtensionProperty(name = "Jim", value = ""),
})
})
- 指定接口错误码
指定之后将会在文档页面定义该接口的错误码
@ApiOperation(value = "获取产品", notes = "获取产品说明。。", extensions = {
// 指定错误码,name固定为code
@Extension(name = "code", properties = {
@ExtensionProperty(name = "100001", value = "id错误"),
@ExtensionProperty(name = "100002", value = "错误描述2"),
@ExtensionProperty(name = "100003", value = "错误描述3")
})
})
# 格式化输出
{
// 调试输出json格式化
"debugPrintFormat": true
}
指定后,推送的内容将会格式化输出
# 优先使用@Api.tags属性(1.2.16)
插件默认使用@Api.value()属性进行分类,如果要使用@Api.tags属性进行分类,则添加如下配置:
// 优先使用@Api.tags属性
// 详见:cn.torna.swaggerplugin.bean.PushFeature
"features": ["USE_API_TAGS"]