为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的可用性。下期咱们再介绍咱们API管理解决方案中提供的在线测试功能，敬请你们关注。

CDIF框架和基于CDIF的API管理解决方案目前由上海灵长软件科技有限公司负责开发，并开放给全部API开发者使用，欢迎你们来咱们的网站 https://apemesh.com 注册并申请试用咱们的API管理解决方案。