我给你聊聊-Torna企业接口文档解决方案

原创
03/14 23:23
阅读数 844

2021年3月10日。国内最大的开源社区机构开源中国正式收录了Torna这个企业接口文档解决方案,Torna开源后就在码云上获得了很多小伙伴的认同,star数量上涨的很快。那么笔者就来和社区的小伙伴聊聊Torna。

Torna的诞生故事

2020年,smart-doc在开源社区发展非常的迅速,在码云平台上突破了1K的star,也获得了社区里许多同学的认同。笔者在开源smart-doc两年的时间里,也收集到了许多来自社区的需求。许多同学很希望smart-doc能够去对接Yapi这个当前国内的比较流行的API管理平台,但是无一例外都被我所决绝了。首先smart-doc在开源之初,在笔者的心里早就规划好了要做一个后端API管理平台的,不过由于时间不允许,在开源社区里也没有找到合适的伙伴,原因其实很简单,整个计划就搁浅了。其次,当前市面的上的开源API管理平台都没法触动到我去将smart-doc接入。总之,骨子里的那种不将就不允许我去将就。

2020年9月,在开源中国诞生了swagger-admin, 一个 Swagger 文档管理后台,发布后我在时不时的关注这款开源作品,我大致浏览了下功能后,我个人不看好这款产品,这可能也和我研究过许多国内外相关产品有一定关系。swagger-admin后来也更新了几个版本,我也去浏览了下@tanghc。从我了解swagger-admin开始,我个人持续观察了有一个多月吧。在这一个多月中,我觉的我找到了一个非常好的开源合作伙伴。@tanghc个人的持续开源能力很强。自己做了好几个开源项目。我相信他一定可以做好我心中想要的开源产品,能够去做一款社区开发者们喜欢的产品。

2020年11月3号,我加@tanghc开源作品的QQ技术群。哈哈,因为我QQ昵称和社区的昵称是一样的,@tanghc一下就认出了我是smart-doc的作者。当然稍微寒暄了几句,我直接把我的想法告诉@tanghc,理念一拍即合。 第二天,我把我收集到的一些需求以及我个人想出来需求列到一个txt文本中发了过去。@tanghc个人就开始了研发工作。在2020年12月16日的时候,@tanghc直接给我了一个部署好Torna的地址,我很吃惊。这么快就搞出来了,开源效率真的和我当初找他的时候内心的判断非常一致。当然Torna这个名字也是他自己想的,关于名字我想后面可以单独让,@tanghc来聊聊。发了需求之后,中间研发的事情我就清楚了。我个人在这一段时间内,也是比较忙。忙年底公司项目的验收事情。我就是拿到Torna登录平台的地址后,登录进去粗略的看了下,提了一些我个人的意见。@tanghc做了些优化和改进。整个优化在12月也都完成。

2021年1月6号,smart-doc启动和Torna的对接。对接的目的就是能够直接将smart-doc生成的JAVA Spring技术栈开发的API文档直接推送到Torna完成统一的管理。在对接过程中由于年关事情多,开源人力不足。直到3月份初才完成了这个对接联调。完成对接联调后。@tanghc启动了Torna的开源。Torna的开源之路开始了。

因为不将就,社区诞生了smart-doc!因为不将就,也开启了Torna的故事。

Torna介绍

前面故事主要是让后面社区里我们的用户能够更加了解Torna。下面正式来介绍下Torna。

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

exmple

Torna项目源码

特性介绍

  • 支持接口文档增删改查
  • 支持导入外部接口(支持导入swagger、postman)
  • 支持OpenAPI管理接口
  • 支持字典管理
  • 支持导出为markdown格式、html格式
  • 支持多环境接口调试
  • 支持文档权限管理,访客、开发者、管理员对应不同权限
  • 提供管理模式浏览模式双模式,管理模式用来编辑文档内容,浏览模式纯粹查阅文档,界面无其它元素干扰
  • 部署简单,直接运行脚本启动程序
  • 支持docker、docker-compose、k8s运行

Smart-doc+Torna API文档流程自动化

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

smart-doc+torna

关于这个组合的优势已经很明显了:

  • Spring项目集成smart-doc,然后直接就生成文档并推送到Torna了。解放了双手。
  • 对于微服务架构就更加明显了,多个服务的文档都能推送Torna做API文档集中化管理。

smart-doc与torna推送对接操作手册

关于Smart-doc+Torna的社区建设

在Java开发的技术栈这块,基于源代码和注释生成文档工具。全社区找不到比Smart-doc更好的工具。smart-doc被科大讯飞、小米、一加、中国移动、中国电信这些知名公司一些技术团队采用也是有原因的。文档完善程度也是国内开源社区中非常有代表性开源项目。smart-doc和相关的maven和gradle插件都属于完全开源的工具,未来也会一直开源。

Torna的诞生已经和Smart-doc在JAVA技术栈开发上形成了一个很多的API文档闭环产品。我和@tanghc合作也是为了给社区提供更加易于使用和自动化的解决方案。当然Torna本身也支持导入swagger、postman这样的文档格式。Torna的很多基础功能我们都会开源。

技术团队

目前Smart-doc+Torna的整个开源方案是由原始Smart-doc和Torna开发一起开发。团队核心开发者都有着多年的研发经验和大厂背景,研发可以从前端干到DevOps。

开源招募

我们非常希望社区里认同Torna和Smart-doc的同学加入我们。Torna和Smart-doc都不要求要很高的技术门槛,我们目前更多的是把开源产品打磨好。

Torna的未来

Torna为了会持续的优化和更新。当然我们也会在未来去思考Torna商业化的版本,商业化的版本主要是面向企业提供许多高级的功能,这些功能未来会慢慢的探索。当然请大家放心,Torna未来出了商业版本,整个Torna也是开源版本+商业版本的并存模式。

如果未来商业版本发布,我也希望社区技术的同学能够对我们多一份理解。也对社区里国内的其他开源作者多一份理解,开源的作者们无一例外都牺牲了许多的个人业余时间,尤其是持续迭代的项目,各种issue和功能开发,文档完善对于开源作者来说都需要很大的毅力。并不是像敲键盘骂骂咧咧那么简单。

致谢

在这里,我非常感谢@tanghc这几个月来开发Torna的辛苦付出,也是Torna的开源作者。在他身上我能学到那种一直充满热情的开源精神。

其次,我也很感谢开源中国这个平台对于Torna的推广和支持。

如果你喜欢torna和smart-doc。请给两个项目一些支持

Torna项目源码

smart-doc项目源码

展开阅读全文
打赏
1
0 收藏
分享
加载中
有两个蛋疼的问题:
1、jar包带源码,按官方文档除了写代码指定路径,其他都试了,结论:无效。
试过插件,无效。
试过<classifier>sources</classifier>,也deploy到nexus了,无效。
2、@PathVariable("userId")这种参数怎么写注释?各种写了就是不出。
07/02 14:41
回复
举报
更多评论
打赏
1 评论
0 收藏
1
分享
返回顶部
顶部