Apideploy 重磅开源,在成熟 API 文档解决方案中又多了一个搅局者

2023年 12月 29日 31.8k 0

背景

当前,在很多中、小型的开发团队或创业团队中,依然用着落后的方式进行着API接口的交互,他们写完文档来写代码,或者,写完代码来补文档,更甚者,文档全靠一张嘴,接口描述信息在IM中沟通飞扬,在联调的过程中前后端相互扯皮、苦不堪言。

当然,也有很多优秀的团队,在使用较成熟的解决方案,诸如:swagger、springfox、springdoc、knife4j、apifox、eolink、smart-doc等等。作者基于自己多年的研发经验,参考和对比了诸如上述国内外多个API管理工具和实现,始终觉得一款精美、高效的API平台工具,对开发者的意义重大。在苦苦找寻与对比下,各API管理工具依旧没有达到作者的期望,于是亲自下场,一怒之下写下了Apideploy。

设计理念

Apideploy遵从以下设计理念:

  • 代码即文档。API文档应该通过代码自动生成,并能保持与代码的同步性,而不是通过手写文档来与前端、测试等进行协作;
  • 主流标准友好。文档应该支持主流的OpenAPI 2(OAS2.0)、OpenAPI 3(OAS3.0)等协议标准,同时需要支持HTTP、WebSocket、SSE等协议;
  • 版本可追溯。每一次的版本迭代,可以快速查阅接口变更的明细,支持不同版本的差异对比,并能支持回滚文档版本;
  • 接口可mock。可以直接在该产品上完成接口的测试、联调甚至接口自动化;
  • 界面要精美。友好的用户界面与交互;
  • 第三方兼容。支持导入常见的API协议标准文档,也支持导出常用的文档格式。

产品架构

Apideploy核心分为两部分:API文档生成SDK+API托管与调试平台。

API文档生成SDK是完全开放源码的,访问https://github.com/apideploy-team 可以查阅。目前仅支持Java语言实现,其他语言社区用户可以贡献,或自行直接通过API托管与调试平台的RESTFull API进行对接。Java语言SDK实现基于javadoc注释方式自动生成API文档(无代码侵入方式),也兼容了基于swagger的实现。具体使用请参考:

API托管与调试平台主要功能包括:项目管理、团队协作、权限管理、API文档托管、文档调试、接口数据mock、版本更新记录、版本对比、个性化文档导出、多格式文档导入等,是一个集API全生命周期管理的平台,非常适合团队协作。目前支持公有云与私有化部署,www.apideploy.com是公有云的解决方案。

文档生成原理

Apideploy推崇文档即代码的设计理念,所以作者强烈推荐基于代码注释的文档生成方式,它不像swagger的实现那么笨重。

基于代码注释生成文档

基于代码注释生成文档,Apideploy的实现参考并依赖了smart-doc的开源代码,smart-doc是一款基于qdox优秀的Java文档解析工具,它很方便的实现了基于代码注释到API文档的过程。

Apideploy开源了Java代码注释生成文档的所有代码。

基于Swagger / OpenAPI的文档生成

在基于Java Web项目开发的Swagger实现中,目前用的比较多的开源实现是Springfox(包括国内的Knife4j)与Springdoc-openapi。Springfox的用户较多,但貌似已经停止更新,已经不再支持springboot3.0+的项目。

Apideploy兼容了springfox和springdoc-openapi的全部实现,所以如果之前的项目使用的是swagger项目,也非常方便切换到Apideploy进行文档托管和测试。

API托管与调试平台预览

相关文章

塑造我成为 CTO 之路的“秘诀”
“人工智能教母”的公司估值达 10 亿美金
教授吐槽:985 高校成高级蓝翔!研究生基本废了,只为房子、票子……
Windows 蓝屏中断提醒开发者:Rust 比 C/C++ 更好
Claude 3.5 Sonnet 在伽利略幻觉指数中名列前茅
上海新增 11 款已完成登记生成式 AI 服务

发布评论