API接口管理之道

 

 

一、API管理的痛点

1. API接口在设计时往往需要编写大量的文档，而且编写完成之后还会经常改动，文档编写维护工作量大。
2. 接口文档编写好后，实际的代码可能会与文档有出入，这个时候文档是不准确的，文档与代码保持修改同步也是一个很大的工作量。
3. 随着接口版本的迭代，接口文档需要同步更新。
4. 有些时候接口会成为对接双方的开发进度瓶颈，因为接口调用会有依赖，类似app的项目，前端会需要调用后端接口，接口功能不实现会影响前端开发进度。
5. 接口开发完以后，做接口测试不方便，特别是接口数量多，参数复杂的情况，测试工作量大。
6. 接口在版本迭代后，旧的接口常常需要做回归测试，这个工作量也是非常大的。

二、解决思路

1. API接口管理系统化或平台化，可以直接在可视化API管理界面上方便的维护接口。而且最好有版本管理和权限管理。
2. 可视化维护好的接口可以直接生成对应语言的代码，节省代码开发量。代码有变更时，最好还可以与界面上的接口进行同步。
3. API界面能够提供模拟接口实现方的调用功能，这样就能解耦接口调用方与服务方的强进度依赖，可以先按API接口的消费方基于接口管理系统或平台模拟调用，待服务方准备好后再真实调用。而且这里的模拟最好能做到自定义规则的模拟返回。
4. 接口实际开发完成后，可以根据接口管理系统或平台的可视化测试界面，直接进行接口的实际调用测试。
5. 接口平台能够支持自动化测试，可以自定义测试案例，然后自动化测试并生成可视化报告。这个功能在旧版本接口复测时非常有用。

当然实际落到系统的话，除了上述的核心功能，还有些关联功能。大致需要的全部功能如下图：

Api接口管理.png

三、解决方案

API接口管理应该是大部分公司都会面临的一个管理问题，因此也有很多现成的轮子可以直接拿来用。

这里结合我使用的经验与找到的案例简单介绍下：

3.1 国内解决方案

1. eoLinker
   官网地址：https://www.eolinker.com
   这是一家国内的在线API管理平台，同时也提供开源精简版本。该平台提供的功能非常全面，除了代码生成与同步这个功能外，基本涵盖了前面提到的解决思路中的所有功能。

2. RAP
   官网地址：http://rapapi.org/org/index.do
   这是阿里巴巴公司的团队做的一个开源的API管理系统，功能也还比较全面。除了没有代码生成与同步、自动化测试、状态码管理功能，解决思路中提到的功能基本都有。

3. CrapApi
   官网地址：http://api.crap.cn/
   这是国内的一个开源的API管理系统，提供了文档管理、项目/组织管理相关的功能，在测试管理与代码管理这块是缺失的。

3.2 国外解决方案

1. SwaggerHub
   官网地址：https://swaggerhub.com/
   这是国外的一个非常有名的基于Swagger的一个在线平台，提供了API全生命周期管理的工具集，基本涵盖了解决思路中提到的全部功能。Swagger是一个开源的设计与描述Rest API的框架，它有自定义的接口规范和很多非常实用的工具集，比如Swagger Editor可以用来设计接口，Swagger Codegen可以用来生成代码和测试桩，Swagger UI可以用来生成可视化接口文档等。

2. apiary
   官网地址：https://apiary.io/
   这是Oracle公司收购的一家API管理的公司，也是一个在线的API管理平台，除了代码生成功能，基本提供了解决思路中提到的所有功能。它有自己定义的接口描述语言API Blueprint。

3. apigee
   官网地址：http://apistudio.io/
   这个也是一个基于Swagger的在线API管理平台，可以做接口管理、接口模拟测试。整体的功能相对比较简单。

3.3. 综合比较

由于上述的平台我没有全部深度使用过，所以就功能易用度不作评价，基于各平台的介绍与简单使用做下分析比较。
从设计上来说，国外的Swagger和apiary都有统一的开源接口规范，这样就有了搭建生态的前提，然后创建对应的工具集就会非常实用有效。这里相比而言Swagger的生态又更加成熟些。
从功能完备度或商业化程度上来说，国内的eoLinker、RAP，国外的Swagger、apiary都还不错；其中以eoLinker、Swagger最为突出。
综合比较下来，个人觉得Swagger是在API管理这方面做得最好的，商用的话eoLinker可以考虑，如果考虑到成本或者需要开源的系统，那RAP系统不错。当然实际需求不同公司是千差万别的，最适合的才是最好的，至于哪个更适合就需要自己根据实际情况去比较了。

四、思路扩展

API接口管理还是很大的应用场景的，特别是移动端开发、前后端分离、微服务化的情况下。这方面不管是做开源、还是做商用版本，还是大有可为的。
而对于开源版本，想做成生态定义个统一规范，再基于规范做工具集、集成平台就会非常利于发展，就像Swagger一样。另外还可以支持与其它接口关联的功能动态集成，这样功能就会越来越强大。
而对于商用版本，功能就需要非常完备，数据安全性和权限管理这些非核心功能也需要做得很好才行，另外最好半开源或阶梯性收费，就像eoLinker一样。不过eoLinker目前还没做到代码生成与同步，这块也是接口管理很大的一个痛点与难点。
当然很多大公司资源比较足，而且需求也有更多的定制要求，这样自开发肯定是更加好的；而小公司选用开源的版本或基于开源版本做定制修改，就会更加划算。

五、扩展介绍

API测试的工具

1. postman
   官网地址：https://www.getpostman.com
   有 Mac, Windows, Linux, and Chrome 各平台对应的软件，可以支持API接口的记录和测试。另外也支持接口的文档化与监控。
2. soapui
   官网地址：https://www.soapui.org/
   自称是最好的REST & SOAP 测试工具，跟Swagger一样都是smartbear这个公司做的产品。可以支持做接口的功能测试、压力测试、安全测试、模拟测试。