使用OAS Validator帮助你规范OpenAPI Spec文档
当前主流的开发RESTful API的做法有两种:Code First和Contract First。Code First指先写代码,然后生成Contract,而Contract First则是先写Contract再写代码实现。
两种做法各有利弊,Code First可以让开发人员先写接口实现,然后利用工具反向生成Contract,优点是快速开发,并能保证接口实现与Contract保证一致,缺点是Contract太过易变容易导致下游应用故障。Contract First则可以让Contract的变动受控,保证下游应用的稳定性,缺点是需要人工来保证接口实现与Contact的一致性,具有一定难度。
对于如何规范管理Contract,新开普软件研究院开源的 OAS Validator 提供了一些思路,下面简单介绍。
合规性校验
OAS Validator支持对使用 OpenAPI V3 编写的Contract文档做合规性校验(也可称之为风格校验)。
在一个微服务架构的系统中,提供RESTful API的组件可能会有很多个,并且由不同开发人员/团队开发,那么在使用这些接口的时候有一个很自然的需求就是希望这些接口(或接口文档)的风格是一致的。OAS Validator的合规性校验做的就是这部分工作。下面举例说明怎么使用合规性校验功能:
- 下载代码: https://github.com/NewCapec-Institute/oas-validator clone
- 然后 mvn clean install 打包
- 到 oas-validator-web/target 目录下执行 java -jar oas-validator-web-exec.jar 启动 OAS Validator Web
- 访问 http://localhost:8080,进入合规性校验功能
- 把 petstore.yaml 内容贴到文本框中然后点击校验得到结果:
$.tags : 至少提供一个 $.openapi : 必须>=3.0.2 $.components.schemas.'Pet'.title : 必须提供 $.components.schemas.'Pet'.properties.'id'.title : 必须提供 $.components.schemas.'Pet'.properties.'name'.title : 必须提供 $.components.schemas.'Pet'.properties.'tag'.title : 必须提供 $.components.schemas.'Error'.title : 必须提供 $.components.schemas.'Error'.properties.'code'.title : 必须提供 $.components.schemas.'Error'.properties.'message'.title : 必须提供 $.info.description : 必须提供 $.paths./pets.get.tags[0] : 不在$.tags所定义的范围内 $.paths./pets.get.responses.200.headers.'x-next' : 必须为upper hyphen case $.paths./pets.post.tags[0] : 不在$.tags所定义的范围内 $.paths./pets/{petId}.get.tags[0] : 不在$.tags所定义的范围内
下面是功能截图:
下面举例解释检查报告的意思:
$.components.schemas.'Pet'.title : 必须提供,前面一段是JsonPath,用来描述出问题的元素/属性的位置,“必须提供”则的意思是没有填写该属性。如下图:
title是一个文档性字段,没有它虽然不影响接口的语义,但是对于下游应用的开发者来说没有它会造成理解上的困难,因此在这里我们把它设定为必填。
再来看这一条报告 $.paths./pets.get.responses.200.headers.'x-next' : 必须为upper hyphen case,同样前面是JsonPath,告诉你该属性应该为Upper Hyphen Case,正确的写法应该是X-Next。和title属性一样Header的大小写不是一个技术问题,但是统一的大小写风格能够让下游应用的开发人员更舒适,从而有更少的Bug。
兼容性校验
不管你是采用Code First还是Contract First,Contract的变动不可避免,那么如何保证变化后的Contract能够对下游应用向下兼容就成了不可回避的问题。这个问题的具体描述就是根据V1.0 Contract开发的下游应用是否依然能够与根据V1.1 Contract实现的接口正确交互。
OAS Validator提供了这种兼容性校验,当然同样只支持OpenAPI V3文档。下面举例说明如何使用这一功能:
我们先提供一个v1.0的OAS Spec:
openapi: "3.0.0" info: version: 1.0 title: Swagger Petstore paths: /pets/{petId}: get: operationId: showPetById tags: - pets parameters: - name: petId in: path required: true schema: type: string responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Pet" components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string
再写一个v1.1的OAS Spec,添加了一个query参数name:
openapi: "3.0.0" info: version: 1.1 title: Swagger Petstore paths: /pets/{petId}: get: operationId: showPetById tags: - pets parameters: - name: petId in: path required: true schema: type: string - name: name in: query required: true schema: type: string responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Pet" components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string
然后同样打开OAS Validator Web,进入“兼容性校验”功能,在左侧贴上v1.0在右侧贴上v1.1,点击校验得到结果:
$.paths./pets/{petId}.get.parameters[1].required : [name=name,in=query]:仅允许新增required=false的parameter
这个报告的意思是新增的query参数name是必填的,这种做法不向下兼容。仔细想想是不是的确如此?
总结
关于OAS Validator的详细文档可见Github。需要注意的是,目前校验规则还不能配置,但是在代码层面提供了接口供扩展,你可以根据自己的需求写一个自己的合规性校验器。
目前OAS Validator已捐赠给Servicecomb Toolkit,同时已整合到Servicecomb Toolkit项目中提供服务,希望能够为广大开发者带来帮助。
最后,欢迎开发者朋友们加入ServiceComb社区,一起做些有意思的事情。加入ServiceComb社区
如果文章对您有帮助,欢迎小伙伴收藏toolkit项目,为项目加Star~
https://github.com/apache/servicecomb-toolkit
2019年度最受欢迎中国开源软件
投票啦!
小伙伴们,2019最受欢迎中国开源软件评选开始啦!
请帮忙给
【开发框架、库类】的Apache ServiceComb
以及
Go Chassis
投票吧!
【投票方式】
1、点【2019年度最受欢迎中国开源软件】进入页面投票
(每人可以投5票)
组织需要你的一臂之力
请给予我们支持和反馈
我们会继续努力
为大家提供更好用的开源软件服务
爱你们!
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
Ubuntu 20.04 LTS 重要里程碑,每日构建 Current 版来了
Ubuntu 20.04每日构建版本镜像现在可以下载并进行测试了。 20.04 是 Ubuntu 的第 8 个 LTS 版本,计划于明年 4 月 23 日发布。直到最终稳定版本发布,每天都会构建新的系统镜像,称为 Daily Build,这些镜像最终将演进到Ubuntu 的下一个长期支持版本 20.04 LTS(Focal Fossa)。 此前Ubuntu CD 镜像服务器上只有pending(待处理)状态的实时镜像可用,但是从 11 月 19 日开始,现在已经有了 Current(当前)状态的镜像,当前状态的镜像已经通过了一系列自动化测试。这是开发周期中的一个重要里程碑。 测试人员与抢鲜的开发者可以安装 Current 状态的每日构建版本镜像并像滚动发行版一样使用,同时在它们到达最终正式版本之前,体验到所有Focal Fossa 更新。理论上讲,一旦安装了 Current 每日构建版本,就可以继续不断安装更新,直到发布为止。 下载地址: http://www.cdimage.ubuntu.com
- 下一篇
Dev 日志 | 一次 Segmentation Fault 和 GCC Illegal Instruction 编译问题排查
摘要 笔者最近在重新整理和编译 Nebula Graph 的第三方依赖,选出两个比较有意思的问题给大家分享一下。 Flex Segmentation Fault——Segmentation fault (core dumped) 在编译 Flex 过程中,遇到了 Segmentation fault: make[2]: Entering directory '/home/dutor/flex-2.6.4/src' ./stage1flex -o stage1scan.c ./scan.l make[2]: *** [Makefile:1696: stage1scan.c] Segmentation fault (core dumped) 使用 gdb 查看 coredump: Core was generated by `./stage1flex -o stage1scan.c ./scan.l'. Program terminated with signal SIGSEGV, Segmentation fault. #0 flexinit (argc=4, argv=0x7ffd25...
相关文章
文章评论
共有0条评论来说两句吧...