一种RESTAPI自动文档生成能力目前，RESTAPI作为大多数移动应用与云服务后台的标准连接方式，已经被大多数开发者所认可和广泛使用。近年来，随着新兴API经济模式的逐渐兴起，不少厂商将后端业务能力以RESTAPI的形式开放给更广泛的第三方开发者。然而，管理RESTAPI并非易事。由于缺乏有效的接口数据模式约束，再加上设计RESTAPI时对资源端点的安排，以及发送http请求的方式多种多样，RESTAPI开发完成后，API开发者仍然需要手工编写API文档在多数情况下。允许用户按照文档中的说明进行访问。并且当API发生变化时，需要重新编写文档，既费时费力又容易出错。例如，一个RESTAPI文档至少要列出以下基本信息：API的名称、API所在的URL资源路径、http请求方式（GET、POST、PUT等）、请求方式API提交数据（查询参数、表单提交、JSON提交等）调用API返回数据的格式在上面提供的RESTAPI信息中，大多数情况下API返回的JSON数据只能使用“examples”来说明数据的结构，并不能准确表达这个JSON数据中各个字段的准确含义和类型定义。这都是因为RESTAPI缺少对JSON数据的模式定义，这种“示例”方式无疑是一种非常无奈和愚蠢的做法。我们在开发中对接其他厂商的接口时，经常会出现对方文档不清晰的情况，需要我们手动确认通信，甚至共同调试我们对某个数据参数的理解或者返回的结果是正确的。这是一个非常费时费力的过程。工作。而当业务发生变化，RESTAPI的上述任何信息发生变化时，比如在返回结果中增加了新的字段，开发者必须重新手动编写文档，然后将文档重新发送给API用户进行修改。上面的过程如果反复迭代会很痛苦。虽然目前有一些API设计和文档工具，比如SwaggerUI，使用Yaml语言来帮助开发者更轻松地编写文档，但它们并没有消除RESTAPI固有的上述复杂性。灵长科技提供的API管理解决方案完美解决了上述RESTAPI文档问题。灵长科技的核心技术是一个名为CDIF的API管理框架。CDIF是世界上第一个基于JSON的SOA解决方案。CDIF管理的所有RESTAPI都可以自动生成API文档，大大节省了开发者管理API文档的时间和精力。CDIF的框架设计可以用下图表示：上图中，CDIF将RESTAPI统一封装到各个驱动包中，每个驱动包都是一个标准的node.jsnpm包。每个驱动程序包都可以包含任意数量的RESTAPI访问代码。在驱动包的实现上，根据CDIF提供的规范，每个RESTAPI都必须为客户端提供一个统一通用的API模型。API模型是一个JSON文档，其中包含有关如何访问API的所有信息。与上述RESTAPI文档相比，该API模型仅包含以下信息：API名称、API输入参数和返回结果的JSONschema定义，其他关于RESTAPI的信息被视为内部API驱动包。实现，不需要暴露给外部API消费者。基于CDIF定义规范的API模型具有与基于XML的WSDL相同能力的API描述。在此基础上，支持CDIF的API管理工具可以自动解析这个JSON文档，自动为它管理的RESTAPI生成一个文档。下图为灵长科技API市场自动生成的清晰易读的短信API文档截图：上图截图详见灵长科技API市场。在上面的API文档中，所有请求和返回数据中的各个字段类型、描述、约束、API错误信息等，都是由API包中用户提供的JSONschema文件自动生成的，真正做到了一个API和数据的100%准确描述。开发者只需要按照CDIF提供的规范定义编写API模型，将一个只有几十行API接入代码的npm包上传到灵长科技的API管理平台，就可以拥有这个能力。当需要更新API参数或返回结果时，用户只需更新npm包中的JSONschema文件内容，重新上传即可自动获取新的API文档。用户在访问CDIF管理的RESTAPI时，只需要访问CDIF为其管理的RESTAPI提供的固定URL地址，只需要客户端支持httpPOST方式提交API请求数据即可。所有提交的数据，根据JSONschema的约束，全部放在HTTP请求和返回的JSONbody中。本设计是经典的WSDL+SOAP实现，非常易用，兼容性好。同时，CDIF借助JSONschema强大的表达能力，可以支持任意复杂的API接口数据。目前大多数流行的开发语言都支持以postJSON数据的形式提交API请求，因此CDIF提供的API访问接口已经可以得到最广泛的客户端开发环境的支持。未来我们会增加自动生成各种语言的客户端API访问码的功能。API用户只需复制粘贴代码即可访问，这将进一步简化和方便API的开发和使用。另外，当API包的内部实现需要改变时，用户只需要修改API包的代码，重新上传并一键部署新版本即可。CDIF支持API包代码的热切换，甚至不会影响线上发生的老版本API的调用过程。这极大地方便和简化了开发者的API开发体验。不仅如此，开发者在上传API包后，还可以自动拥有一个API测试页面，让API开发者和API用户更方便地调试API的可用性。下一期我们会介绍我们提供的这个功能，敬请关注。CDIF框架和基于CDIF的API管理解决方案目前由上海领畅软件技术有限公司开发，面向所有API开发者开放。欢迎访问我们的网站www.apemesh.com注册并申请试用我们的API管理解决方案。
