java微服务下的接口文档该如何管理

接口文档的发展

技术的快速迭代，使得服务的架构快速变化，文档工具也跟着服务的升级经历了以下阶段：

1. 前后端不分离的单体服务，不需要文档阶段
2. 前后端分离的单体服务，手写文档阶段
3. 微服务下Swagger、Openapi为主流的文档生成工具

主流文档工具的弊端

然而随着近年来微服务的热度日渐高涨，许许多多的公司进入都开始进行微服务的转型。越来越多的公司加入更加促进了微服务框架的快速迭代。慢慢的Swagger、Openapi为主流的文档工具就缺陷就体现了出来：

• 学习成本高
• 耗时
• 功能单一

什么才是我们需要的

那么有什么更好的办法去解决呢？我们的诉求又是什么，经过长时间思考我得到以下结论：

• 安全，如今的微服务发展已经不仅限于对外的接口，还有服务和服务之间的接口，安全的问题自然不言而喻。
• 学习成本低
• 便捷，快速
• 包含mock，请求，文档，等功能，需要强大且易扩展
• 集中，微服务下的文档集中可以让我们加快速的了解到那些接口是对外，那些是对内，且同时可以了解到当前接口是那些服务调用了。以便于我们后期维护
• 兼容，微服务的快速发展，让世面上产生了很多种不同的框架，许多时候，不同的项目都是不同的 框架构成。
• 零侵入，Swagger、Openapi侵入性不言而喻，当我们不再使用其中一个框架作为文档工具，或者产生新的需求时，我们往往无法进行文档的重构，繁重的任务会压垮所有开发者。
  满足如此之多的需求。
  那么满足如此之多的需求，该如何才能解决呢，或者说，是否已经有了已经出现的技术去完成这项工作?答案是显而易见的

新一代的接口文档管理工具

经过在众多的开源项目中寻找，有一个项目引起了我的注意 smart-doc+Torna,该项目已经是一个成熟项目，许许多多的公司在使用，在Gitee上的点赞也到达3.1k。
Torna是一个前后端分离的web项目，由前段由Vue 后端由Java 构成。Torna提供了文档的编辑，管理，权限，以及接口的请求，mock等功能，是一个标准且强大的接口文档管理工具。

而Smart-doc则提供了一种新的理念去解析接口，参数校验注解+javadoc tag。什么是参数校验注解呢？其实就是接口请求参数做限制时，用的@Length @Max @NotNull等，而javadoc tag则是

在书写代码时候必须要写的注释，smart-doc还提供了许多java以外的tag，以便于更好的对文档进行管理，只需要书写对应的注释，以及必须的参数校验注解，smart-doc便可以解析，并且，当配置好对应的Torna参数后，smart-doc便可以使用maven插件进行文档的统一上传，详情请查看https://gitee.com/smart-doc-team/smart-doc

Idea插件 Restful Cloud +Torna

上面说到smart-doc的理念，本人自认为是很超前的，注释和文档都是对代码的描述，用注释的方式去解决文档的问题，也终将是文档工具的最终归途。
于是历经多月，秉持smart-doc的理念开发了一个IDEA 插件 Restful Cloud,
源码地址：https://gitee.com/bamboo-qiqing/Restful-Cloud
文档地址：https://bamboo-qiqing.github.io/projects/restfulCloud/home.html

Restful Cloud 提供了那些功能

接口地址的搜索（快捷键Ctrl+Q）

导出，上传，重命名

不同项目的筛选

扩展

Restful Cloud 使用了Sqlite文件型数据库缓存了所有已经加载过项目的api。并且所有的配置和接口信息都内置在sqlite表中，所以可以更加方便和快捷的进行不同注解以及不同平台搜索的扩展。