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自动化测试。
API的文档自动生成——基于CDIF的SOA基本能力的更多相关文章
- swagger:API在线文档自动生成框架
传统的API从开发测试开始我们经常借用类似Postman.fiddle等等去做接口测试等等工具:Swagger 为API的在线测试.在线文档提供了一个新的简便的解决方案: NET 使用Swagger ...
- springboot成神之——swagger文档自动生成工具
本文讲解如何在spring-boot中使用swagger文档自动生成工具 目录结构 说明 依赖 SwaggerConfig 开启api界面 JSR 303注释信息 Swagger核心注释 User T ...
- Word 2010文档自动生成目录和某页插入页码
一.Word 2010文档自动生成目录 关于Word文档自动生成目录一直是我身边同学们最为难的地方,尤其是毕业论文,经常因为目录问题,被要求修改,而且每次修改完正文后,目录的内容和页码可能都会发生变化 ...
- VS文档自动生成
VS2008文档自动生成 (发现,Sandcastle主要是用于C#项目.里面的注释都是XML格式的.不太适合VC的.最终还是得用Doxygen) 一.Sandcastle简介: Sandcastle ...
- django接口文档自动生成
django-rest_framework接口文档自动生成 只针对用到序列化和返序列化 一般还是用第三方yipi 一.安装依赖 pip3 install coreapi 二.设置 setting.py ...
- Api文档自动生成工具
java开发,根据代码自动生成api接口文档工具,支持RESTful风格,今天我们来学一下api-doc的生成 作者:互联网编程. 欢迎投稿,一起交流技术 https://www.jianshu.co ...
- 优于 swagger 的 java markdown 文档自动生成框架-01-入门使用
设计初衷 节约时间 Java 文档一直是一个大问题. 很多项目不写文档,即使写文档,对于开发人员来说也是非常痛苦的. 不写文档的缺点自不用多少,手动写文档的缺点也显而易见: 非常浪费时间,而且会出错. ...
- 如何让接口文档自动生成,SpringBoot中Swagger的使用
目录 一.在SpringBoot项目中配置Swagger2 1.pom.xml中对Swagger2的依赖 2.编写配置类启用Swagger 3.配置实体类的文档 4.配置接口的文档 5.访问文档 二. ...
- java 文档自动生成的神器 idoc
写文档 作为一名开发者,每个人都要写代码. 工作中,几乎每一位开发者都要写文档. 因为工作是人和人的协作,产品要写需求文档,开发要写详细设计文档,接口文档. 可是,作为一个懒人,平时最讨厌的一件事情就 ...
随机推荐
- flex控件总结
Flex基本控件总结 一.flex控件的分类:文本控件(text controls).数据源控件(data provider controls).菜单控件 (menu controls) ...
- 什么是Bootstrap?
简介 - 框架:库 lib library- jQuery作为一个框架来讲,提供一套比较便捷的操作DOM的方式- 把大家都需要的功能预先写好到一些文件 这就是一个框架- Bootstrap 让我们的 ...
- Java三大修饰符
1.static 修饰: 修饰属性:类变量,全类共有 修饰方法:静态方法,静态方法中不能直接访问非静态的方法和属性 静态方法只能被静态方法覆盖,并且没有多态 静态的方法或者属性不依赖于对象:类名.方法 ...
- 用js实现文字提示层 ---总结
文字提示层在项目中应该是比较常见的,我工作中项目中就用到了,原理是一样,只不过形式不一样,今天通过看视频学习,学会了,总结下: 首先,页面效果如下: 需求: 当鼠标移入到红色字体是,提示框会显示在下 ...
- 理解InnoDB的事务隔离级别
隔离是ACID(Atomicity,Consistency,Isolation,Durability)的重要部分,它保证事务以一种可靠的方式运行.隔离确保同时运行的事务并不相互干扰.隔离确保数据一致性 ...
- ubuntu12.04下安装pptp_vpn服务器
1.下载安装apt-get install pptpd 2.配置/etc/pptpd.confvim /etc/pptpd.conf添加下面两行(在配置文件的最后取消注释修改IP即可)localip ...
- Android开发10:传感器器及地图相关应用
前言 啦啦啦~各位小伙伴们好~经过这一学期的Android知识的学习,我们学到了很多和Android开发相关的知识,这一学期的学习也要告一段落了. 一起进入我们今天的相关内容~这次我们将一起学习使用 ...
- 前端总结·基础篇·CSS(二)视觉
前端总结系列 前端总结·基础篇·CSS(一)布局 前端总结·基础篇·CSS(二)视觉 前端总结·基础篇·CSS(三)补充 前端总结·基础篇·CSS(四)兼容 目录 一.动画(animation)(IE ...
- angular.js学习笔记:实现商品价格计算实例
<!DOCTYPE html> <html lang="en" ng-app> <!-- ng-app:初始化的指令 也可以解析局部--> &l ...
- Linux 下文件操作 shell
删除目录下的所有文件ls *.log | xargs rm -f当前目录所有文件大小的总和ll | awk '{sum += $5}; END {print sum/1048576}'将命令推送到后台 ...