我们为什么需要API管理系统?

6,776 阅读7分钟

我们为什么需要API管理系统?

随着web技术的发展,前后端分离成为越来越多互联网公司构建应用的方式。前后端分离的优势是一套Api可被多个客户端复用,分工和协作被细化,大大提高了编码效率,但同时也带来一些“副作用”:

  1. 接口文档不可靠。很多小伙伴管理接口文档,有使用wiki的,有word文档的,甚至还有用聊天软件口口相传的,后端接口对于前端就像一个黑盒子,经常遇到问题是接口因未知原因增加参数了,参数名变了,参数被删除了。
  2. 测试数据生成方案没有统一出口。我们都有这样的经历,前端开发功能依赖后端,解决方案有自己在代码注入json的,还有后端工程师临时搭建一套测试数据服务器,这种情况下势必会影响工作效率和代码质量,也不能及时进行更新。
  3. 资源分散,无法共享。接口调试每个开发者单独维护一套Postman接口集,每个人无法共用其他人的接口集,存在大量重复填写请求参数工作,最重要的是postman没法跟接口定义关联起来,导致后端没有动力去维护接口文档。

除了以上三点,对于我们公司的开发流程又会出现以下问题:

  1. 由于咱们公司的开发形式为多任务并行,前端与后端齐头并进各自开发,虽然原型只有一份,但是每个人的理解可能不止一种,这就导致当前后端都完成各自的前置后进行接口对接时出现字段不一致,多字段或少字段等问题,然后其中一方甚至双方对之前产出的代码进行更改,这里就会浪费大量的时间。
  2. 现在咱们项目的接口文档主要依靠word进行编写,一旦接口出了问题,更改文档的过程会十分繁琐耗时。

除了以上问题之外,我们可能还会遇到一些其他问题,比如文档的导出,模块的划分,操作的便捷性等等。带着这些问题我对国内外的一些接口管理系统做了简单的调查,推荐度较高的有一下几个:

有哪些好用的API管理系统?

  1. 阿里妈妈前端团队出品的rap,目前有两个版本,rap1rap2这个是我相当推荐的一款应用,随便一搜rap1绝对是被力荐的那一个,它操作简单,项目模块划分清晰,能够进行多版本的回退,可以把接口直接复制或者移动到另一个地方并且还是开源的。不过缺点也挺明显,没有导出功能,无法mock数据,线上demo没法使用,貌似现在已经没人在维护了,但是即便是这样他还是被众多网友推荐,当然在rap1的使用过程中还是很顺滑的。免费开源
  2. Swagger是全球最大的API开发框架,这个框架以“开放API声明(OpenAPISpecification,OSA)”为基础,支持整个API生命周期的开发。它可以和SpringMVC整合,并且通过结合Swagger-ui组件,将controller层的方法进行可视化的展示,像方法注释,方法参数,方法返回值等都提供了相应的用户界面。收费
    • 优点:

      • 在线生成API文档并测试,易维护;
      • 可以和多种不同框架整合(除了SpringMVC,还有struts2,jersey2,cxf等等),应用范围广;
      • 测试的时候不需要再使用浏览器输入URL的方式来访问Controller,使用简单方便,学习成本低。
    • 缺点:

      • 没有导出的功能,文档只能在线看及在线测试,不能导出到本地。
      • 部署比较麻烦,不易上手,对开发者的英文要求较高。
  3. eolinker真的也很好用,ui好看,可导入导出,版本回退,能够mock数据,而且还是不断地迭代中,相信后面会有越来越多的新功能,也能够更贴近用户实际需求。不过他有一个缺点而且还很致命,就是得花钱。。免费版的只能加入五个开发人员,只能导出为eolinker和HTML格式,想要体验其他功能就得付费喽。部分收费
  4. YApi 是高效、易用、功能强大的 api 管理平台,旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API,YApi 还为用户提供了优秀的交互体验,开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。Apache License 2.0
    • 优点:
      • 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档,效率提升多倍
      • 扁平化权限设计,即保证了大型企业级项目的管理,又保证了易用性
      • 类似 postman 的接口调试
      • 自动化测试, 支持对 Response 断言
      • MockServer 除支持普通的随机 mock 外,还增加了 Mock
      • 期望功能,根据设置的请求过滤规则,返回期望数据
      • 支持 postman, har, swagger 数据导入
      • 免费开源,内网部署,信息再也不怕泄露了
    • 缺点:
      • 如果要强行加个缺点的话,就是项目的模块划分不太合理,比如:生产排程-工厂日历,这么 一个层级关系它是体现不出来的。
  5. showdoc是一个非常适合IT团队的在线文档分享工具,它可以加快团队之间沟通的效率。免费开源
    • 特性
      • API文档( 查看Demo)随着移动互联网的发展,BaaS(后端即服务)越来越流行。服务端提供API,APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。
      • 数据字典( 查看Demo)一份好的数据字典可以很方便地向别人说明你的数据库结构,如各个字段的释义等。
      • 说明文档 你完全可以使用showdoc来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅
    • 功能
      • 分享与导出
        • 响应式网页设计,可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件,以便离线浏览。
      • 权限管理
        • 响公开项目与私密项目
        • ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问,而私密项目则需要输入密码验证访问。密码由项目创建者设置。
      • 项目转让
        • 项目创建者可以自由地把项目转让给网站的其他用户。
      • 项目成员
        • 你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑,但不可转让或删除项目(只有项目创建者才有权限)
      • 编辑功能
        • ShowDoc采用markdown编辑器,无论是编辑还是阅读体验都极佳很棒。如果你不了解Markdown,请在搜索引擎搜索"认识与入门 Markdown"
        • 在ShowDoc的编辑页面,点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。插入模板后,剩下的就是改动数据了,省去了很多编辑的力气。
      • 历史版本
        • ShowDoc为页面提供历史版本功能,你可以方便地把页面恢复到之前的版本。
  6. 易文档,让您轻松编写和维护高质量的文档。从需求文档、API文档、部署文档到使用手册,不同类型文档,满足您整个开发周期需求。 让协作者一看就懂,让接手人不再只能翻看代码上手, 这是一个让编写者感到畅快、阅读者舒心、沟通更顺畅的文档平台。不只是API管理

结语

本文只是列举出了我自己的比较中意的一些API管理平台,精力有限并未一一进行详细体验,读者有感兴趣的可以自行体验一下。

参考资料

有没有开源的api管理系统? - 刘长风的回答 - 知乎

YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台