一种REST API自动化文档生成能力
当前,作为大部分移动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的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的文档。下图是灵长科技的API市场上自动生成的清晰易读的短信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框架和基于CDIF的API管理解决方案目前由上海灵长软件科技有限公司负责开发,并开放给所有API开发者使用,欢迎大家来我们的网站 apemesh.com注册并申请试用我们的API管理解决方案。