REST API自动生成文档
目前，作为大多数移动app与云服务后台之间的标准连接方式，REST API得到大多数开发人员的认可和广泛应用。 近年来，新兴API经济模式兴起，许多厂商将自己的后台业务能力作为REST API开放，用于更广泛的第三方开发者。
但是，管理REST API并不是一项容易的工作。 由于缺少有效接口数据的架构约束、设计REST API时的资源端点调度以及发送http请求的方式各种各样，因此在REST API开发完成后，API开发通常仍然存在此外，如果API发生更改，则必须重写文档。 这个过程很费事，容易发生错误。 例如，REST API文档必须至少包含以下基本信息：
API的名称
API所在的URL资源的路径
http请求方法(获取、开机自检、上传等) ) ) ) )。
API提交数据的方式(查询参数、表单提交、JSON提交等)。
调用API返回数据格式
在上面的REST API信息中，从API返回的JSON数据在大多数情况下只能通过“示例”说明数据的结构，而不能准确表达此JSON数据中每个字段的确切含义和类型定义。 这是因为REST API缺少JSON数据的模式定义，这种“示例”方法无疑是无能为力和愚蠢的做法。 当我们在开发过程中连接其他制造商的接口时，对方的文档往往会变得不清楚。 手动检查交流，或者联合理解某些数据参数和返回的结果是否正确是一项非常耗时的工作。
如果业务发生了变化，上述有关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包。 每个驱动器包可以包含任意数量的REST API访问代码。 在驱动程序包实现中，每个REST API都必须为客户端提供统一的通用API模型，这取决于CDIF提供的规范。 此API模型是一个JSON文档，其中包含有关如何访问此API的所有信息。 与上述REST API文档相比，此API模型只包含以下信息：
API的名称
返回API输入参数和结果的JSON架构定义
所有有关REST API的其他信息都被认为是API驱动程序软件包的内部实现，不需要向外部API用户暴露。
基于CDIF定义规范的API模型具有与基于XML的WSDL相同的API描述。 而且，与CDIF相结合的API管理工具可以自动解析该JSON文档，并从中自动生成管理REST API的文档。 下图是灵长类科技API市场自动生成的易读的消息API文档的屏幕截图：
以上截图详情请参考灵长类API市场
在上述API文档中，所有请求和回复数据中的每个字段的类型、说明、约束条件、API错误消息等都是由用户在API包中提供的JSON架构文件自动生成的，实际上是100%的API和数据开发人员只需根据CDIF提供的规范定义创建API模型，然后将只包含几十行API访问代码的npm软件包上传到灵长类API管理平台，就可以实现这一能力。 如果需要更新API参数或返回的结果，用户只需更新npm包中JSON架构文件的内容并重新上传，即可自动获取新的API文档。
访问此CDIF管理的REST API时，用户只需要访问为CDIF管理的REST API提供的固定URL地址，客户端只需支持http POST方法即可发送API请求数据。 根据JSON架构的限制，提交的所有数据都将放入http请求和返回的JSON body中。 这种设计是经典的WSDL SOAP实现方式，非常简单易用，兼容性强。 此外，JSON方案的强大性能使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开发者使用。
欢迎大家来我们的网站 www.apemesh.com注册并申请试用我们的API管理解决方案。