API的文档自动生成——基于CDIF的SOA基本能力

当前，作为大部分移动app和云服务后台之间的标准连接方式，REST API已经得到了绝大部分开发者的认可和广泛的应用。近年来，在新兴API经济模式逐渐兴起，许多厂商纷纷将自己的后台业务能力作为REST API开放出来，给更广泛的第三方开发者使用。

 

但是，管理REST API并非是一件容易的工作。由于缺乏有效的接口数据schema约束，加上设计REST API时resource endpoint的安排，以及发送http请求的方式又都五花八门，REST API开发完成后，大多数情况下API开发者仍然需要手动书写API文档，让用户能按照文档的说明接入。并且在API发生变化时需要重写文档，这个过程费时费力而且容易出错。比如，一个REST API文档最少必须列明以下的基本信息：

 

* API的名称

* API所在的URL资源路径

* http请求方法（GET, POST, PUT等）

* API提交数据的方式（查询参数、表单提交、JSON提交等）

* 调用API返回数据的格式

 

在上面提供的REST API信息中，从API返回的JSON数据在大部分情况下甚至只能用“举例”的方法说明数据的结构，而无法精确表达出这段JSON数据中每个字段的精确含义和类型定义。这都是因为REST API缺少对JSON数据的schema定义而导致，而这种“举例”的方式毫无疑问是一种很无奈很傻的做法。我们在开发时对接其他厂商的接口时，经常会发生对方的文档不清晰，需要人工确认交流，甚至联调我们对某个数据参数或者返回结果的理解是否正确，这是一个非常耗时耗力的工作。

 

而当业务发生变化，以上任何一项关于REST API的信息发生变化时，比如返回结果里添加了一个新的字段，开发者又必须重新手工书写文档，然后把文档重新发送给API使用者更改，以上的过程如果反复迭代则会非常痛苦。当前虽然有一些API设计和文档工具，比如Swagger UI等用Yaml语言帮助开发者更容易地书写文档，但并没有消除REST API天生带来的上述复杂性。

 

这种API管理解决方案则完美地解决了上述的REST API文档问题。CDIF是世界上第一个基于JSON的SOA解决方案。被CDIF管理的REST API都可以自动生成他们的API文档，大大节省了开发人员管理API文档的时间精力。CDIF的框架设计可以用下图表示：

 

在上图中，CDIF将REST API统一封装成各种驱动包，每个驱动包都是一个标准的node.js npm package。每个驱动包中可包含任意多条REST API的访问代码。在驱动包的实现中，按照CDIF提供的规范，每个REST API必须为客户端提供一个统一通用的API模型。这个API模型是一份JSON文档，里面包含了所有关于如何访问这个API的信息。而相比起以上的REST API文档，这份API模型中仅仅包含以下信息：

 

* API的名称

* API输入参数和返回结果的JSON schema定义

 

而关于REST API的其他信息都被看成是API驱动包的内部实现，不需要暴露给外部API使用者。

 

基于CDIF定义规范的API模型拥有与基于XML的WSDL同等能力的API描述。在此基础上，与CDIF配套的API管理工具可以自动解析这份JSON文档，并自动从中生成被其管理REST API的文档。下图是利用CDIF制作的API市场上自动生成的清晰易读的短信API文档截图：

 

 

在以上的API文档中，所有请求和返回数据中每个字段的类型，说明，约束条件，API的错误信息等等，全部都从用户在API包中提供的JSON schema文件中自动生成，并且真正做到了对API以及数据100%准确的描述。开发者只需要按照CDIF提供的规范定义写好API模型，上传一个仅包括几十行API访问代码的npm包到灵长科技的API管理平台，便可拥有该能力。而在API参数或返回结果需要更新时，用户只需要更新npm包中的JSON schema文件的内容，重新上传便可自动获得新的API文档。

 

而访问这个被CDIF管理的REST API时，使用者只需要访问CDIF为被其管理的REST API提供的一个固定URL地址便可，并且也只需要客户端支持http POST方法即可提交API请求数据。所有提交的数据，按照JSON schema的约束，全部都放在http请求和返回的JSON body中。这样的设计是经典的WSDL + SOAP的实现方式，非常简单易用而且兼容性好。同时，借助于JSON schema的强大表现能力，CDIF可以支持任意复杂度的API接口数据。目前绝大多数流行的开发语言都支持用post JSON数据的方式提交API请求，所以CDIF提供的API访问接口已经可以得到最广泛的客户端开发环境支持。在将来，我们会添加各种语言的客户端API访问代码自动生成能力，API使用者只需拷贝粘贴代码即可接入，更进一步简化方便API的开发和使用流程。

 

另外，在API包的内部实现需要变化时，用户只需要修改API包的代码，重新上传并可一键部署新版本使用。CDIF支持对API包代码的热切换，甚至不会影响线上正在发生的对老版本API的调用过程。这样大大方便和简化了开发者的API开发体验。

 

不仅如此，上传API包后开发者还可以自动拥有API测试页面，可供API开发者和API使用者更方便地调试API的可用性。这个功能，敬请大家参考上一篇文章：基于CDIF实现的——API自动化测试。