Torna 1.9.0 发布,企业接口文档解决方案

来源: 投稿
2021-06-28

Torna 1.9.0 发布,本次更新内容如下:

- 【新增】排序字段,可调整文档/参数顺序
- 【增强】文档表格新增收缩/展开控制
- 【修复】修复swagger插件泛型参数展示问题
- 【修复】修改文档空指针问题
- 【修复】导入postman空指针问题

此外swagger插件更新到了1.1.0,支持第三方类处理。

接口返回第三方类,但是没有写swagger注解,生成的文档没有描述、示例等信息,如mybatis-plus中的Page<T>类。

@ApiOperation(value = "第三方类演示")
@PostMapping("query")
public Result<Page<OrderDetail>> query(@RequestBody OrderQuery query) {
    return Result.ok(new Page<>());
}

在配置文件中定义一个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注解。

关于Torna

企业接口文档解决方案,目标是让文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护项目API文档,将不同形式的文档纳入进来,形成一个统一的维护方式。

Torna弥补了传统文档生成工具(如swagger)的不如之处,在保持原有功能的前提下丰富并增强了一些实用的功能。

推荐组合

smart-doc + Torna实现文档全流程自动化

如果您使用Java语言,推荐使用smart-doc + Torna

smart-doc + Torna 组成行业领先的文档生成和管理解决方案,使用smart-doc无侵入完成Java源代码和注释提取生成API文档,自动将文档推送到Torna企业级接口文档管理平台。

通过这套组合您可以实现:只需要写完Java注释就能把接口信息推送到Torna平台,从而实现接口预览、接口调试。

推送的内容有:接口名称/author/Path参数/Header/请求参数/返回参数/字典列表/公共错误码

如果您是非Java语言,可以使用表单页面编辑以上内容,完成后同样可以进行接口预览、调试。

展开阅读全文
10 收藏
分享
加载中
最新评论 (1)
今天刚折腾完,感觉还是很不错的
2021-06-28 18:57
0
回复
举报
更多评论
1 评论
10 收藏
分享
返回顶部
顶部