使用OAS Validator帮助你规范OpenAPI Spec文档

最新推荐文章于 2025-03-28 09:18:22 发布
最新推荐文章于 2025-03-28 09:18:22 发布
阅读量855 收藏
点赞数
分类专栏： 技术剖析 文章标签： API OAS Validator
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/looook/article/details/103094572
版权

当前主流的开发RESTful API的做法有两种：Code First和Contract First。Code First指先写代码，然后生成Contract，而Contract First则是先写Contract再写代码实现。

两种做法各有利弊，Code First可以让开发人员先写接口实现，然后利用工具反向生成Contract，优点是快速开发，并能保证接口实现与Contract保证一致，缺点是Contract太过易变容易导致下游应用故障。Contract First则可以让Contract的变动受控，保证下游应用的稳定性，缺点是需要人工来保证接口实现与Contact的一致性，具有一定难度。

对于如何规范管理Contract，新开普软件研究院开源的OAS Validator[1]提供了一些思路，下面简单介绍。

OAS Validator支持对使用OpenAPI V3[2]编写的Contract文档做合规性校验（也可称之为风格校验）。

在一个微服务架构的系统中，提供RESTful API的组件可能会有很多个，并且由不同开发人员/团队开发，那么在使用这些接口的时候有一个很自然的需求就是希望这些接口（或接口文档）的风格是一致的。OAS Validator的合规性校验做的就是这部分工作。下面举例说明怎么使用合规性校验功能：

  1. 下载代码： https://github.com/NewCapec-Institute/oas-validator clone

  2. 然后 mvn clean install打包

  3. 到oas-validator-web/target目录下执行java -jar oas-validator-web-exec.jar启动OAS Validator Web

  4. 访问 http://localhost:8080，进入合规性校验功能

  5. 把 petstore.yaml （https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/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所定义的范围内

下面是功能截图：

640?wx_fmt=png

下面举例解释检查报告的意思：

$.components.schemas.'Pet'.title : 必须提供，前面一段是JsonPath[3]，用来描述出问题的元素/属性的位置，“必须提供”则的意思是没有填写该属性。如下图：

640?wx_fmt=png

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[4]，同时已整合到Servicecomb Toolkit项目中提供服务，希望能够为广大开发者带来帮助。

最后，欢迎开发者朋友们加入ServiceComb社区，一起做些有意思的事情。加入社区方法[5]

如果文章对您有帮助，欢迎小伙伴收藏toolkit项目，为项目加Star~

https://github.com/apache/servicecomb-toolkit

[1] OAS Validator https://github.com/NewCapec-Institute/oas-validator

[2] OpenAPI V3 https://github.com/OAI/OpenAPI-Specification

[3]JsonPath https://github.com/json-path/JsonPath

[4] Servicecomb Toolkit https://github.com/apache/servicecomb-toolkit

[5]加入Servicecomb社区http://servicecomb.incubator.apache.org/cn/docs/join_the_community/

小伙伴们，2019最受欢迎中国开源软件评选开始啦！

请帮忙给

【开发框架、库类】的Apache ServiceComb

640?wx_fmt=png

以及  

Go Chassis

640?wx_fmt=png

投票啦！

【投票方式】

1、识别二维码直接投票

640?wx_fmt=png

2、点文末阅读原文进入页面投票

（每人可以投5票）

组织需要你的一臂之力

请给予我们支持和反馈

我们会继续努力

为大家提供更好用的开源软件服务

爱你们！

openapi-spec-validator:OpenAPI Spec验证器
05-01
OpenAPI Spec验证器 关于 OpenAPI Spec验证器是一个Python库，可根据和规范验证OpenAPI规范。 验证者旨在检查是否完全符合规范。 安装 $ pip install openapi-spec-validator 或者，您可以下载代码并从存储库安装： $ pip install -e git+https://github.com/p1c2u/openapi-spec-validator.git#egg=openapi_spec_validator 用法 命令行界面 直截了当的方式： $ openapi-spec-validator openapi.yaml 管道方式： $ cat openapi.yaml | openapi-spec-validator - 码头工人的方式： $ docker run -v path/to/openapi.yaml
掌控API质量的利器：OpenAPI Validators
gitblog_00014的博客
06-02 301
掌控API质量的利器：OpenAPI Validators OpenAPIValidatorsUse Jest or Chai to assert that HTTP responses satisfy an OpenAPI spec项目地址:https://gitcode.com/gh_mirrors/op/OpenAPIValidators 在现代Web开发中，RESTful API成为服务...
openapi-spec-validator：验证OpenAPI规范的强大工具
最新发布
gitblog_00659的博客
03-28 1025
openapi-spec-validator：验证OpenAPI规范的强大工具 openapi-spec-validator OpenAPI Spec Validator is a CLI, pre-commit hook and python package that validates OpenAPI Specs a...
OpenAPI Validators：确保API文档与实际行为一致的利器
gitblog_01083的博客
09-09 419
OpenAPI Validators：确保API文档与实际行为一致的利器 OpenAPIValidatorsUse Jest or Chai to assert that HTTP responses satisfy an OpenAPI spec项目地址:https://gitcode.com/gh_mirrors/op/OpenAPIValidators 项目介绍 在现代软件开发中，API文...
openapi-validator：用于OpenAPI文档的可配置和可扩展的validatorlinter
02-23
OpenAPI验证器 使用此命令行工具，您可以根据OpenAPI文档的规范或以及IBM定义的最佳实践来对其进行验证。 先决条件 节点10.x NPM 5.x 目录 入门 验证器分析您的API定义并报告其中的任何问题。 验证器是高度可定制的，并且支持OpenAPI 3.0和OpenAPI 2.0（Swagger 2.0）格式。 该工具还支持的许多规则。 您可以使用自定义规则轻松扩展该工具，以满足您的特定需求并确保符合标准。 默认配置同时使用OpenAPI 3.0规则和Spectral规则。 部分描述了这些规则。 通过开始，然后在您的API定义上。 客制化 您可以为您的项目修改验证器的行为，以满足您的首选标准。 可以关闭特定的验证“规则”，或将其配置为在验证器输出中触发错误，警告，信息或提示消息。 甚至可以进一步配置某些验证，例如，切换参数名称的大小写约定。 当前还存在一些无法禁用或配置
oas：轻松创建和管理OpenAPI文档
02-10
它将引导您逐步了解如何使用OpenAPI 3.0规范记录API。 昂首阔步 oas使用 ，可让您在代码上方的注释中包含一个OpenAPI片段，并将它们全部收集到一个OpenAPI文件中： /* * @oas [get] /pet/{petId} * description: ...
OpenAPI Specification 3.1.0 开放API规范
05-27
OpenAPI规范，全称为OpenAPI Specification，是一种定义RESTful API的标准，它独立于任何特定的编程语言，旨在帮助开发者和用户无需查看源代码或阅读大量文档就能理解和使用API。OpenAPI规范的最新版本是3.1.0，它极...
openapi-psr7-validator:它根据 OpenAPI 规范验证 PSR-7 消息（HTTP 请求响应）
07-24
OpenAPI (OAS) 条款 包中使用了一些特定的术语。 这些术语来自 OpenAPI： specification - 描述 API 的 OpenAPI 文档，以 JSON 或 YAML 文件表示 data - 我们根据规范验证的实际事物，包括正文和元数据 schema - ...
zero-rails_openapi：简洁的DSL，用于为Ruby应用程序生成OpenAPI规范3（OAS3）JSON文档
02-06
简洁的DSL，用于为Rails应用程序生成OpenAPI规范3（ OAS3 ，以前为Swagger3）JSON文档。 class Api :: ExamplesController < ApiController api :update , 'POST update some thing' do path :id , Integer ...
openapi-validator-middleware:使用Swagger（Open API）和AJV进行输入验证
05-02
openapi-validator-中间件 该软件包根据在Express，Koa或Fastify应用程序中提供数据验证。 它在使用进行验证。 注意：随着该软件包的发展，我们增加了对OpenAPI定义的支持，同时还增加了对更多框架（如Koa和Fastify）的支持，我们最终采取了将名称更改为更好地描述它。 截至目前，我们将改用名称 。 有在更改代码openapi-validator-middleware@2.0.0相比express-ajv-swagger-validation@1.2.0从名称的改变分开。 目录 fastifyOptions openapi-validator-middleware.init（pathToSwaggerFile，选项） openapi-validator-middleware.initAsync（pathToSwaggerFile，选项） 选项
Python库 | openapi-spec-validator-0.2.4.tar.gz
05-20
资源分类：Python库 所属语言：Python 资源全名：openapi-spec-validator-0.2.4.tar.gz 资源来源：官方 安装方法：https://lanzao.blog.youkuaiyun.com/article/details/101784059
express-oas-validator:Express OpenAPI规范（OAS）中间件验证器
04-07
Express-Oas-validator Express OpenAPI Specification（OAS）中间件验证器和响应验证器。 该软件包将公开一个快速的中间件，该中间件将根据您的OpenAPI文档验证您的终结点，并提供一个响应验证器，以对响应有效负载执行相同的操作。 安装 使用节点程序包注册表进行安装： npm install --save express-oas-validator 用法 这是此程序包的基本用法。 const express = require ( 'express' ) ; // We recommed to install "body-parser" to validate request body const bodyParser = require ( 'body-parser' ) ; const { init , validateMiddl
spec:openapi规范对象模型
05-02
OAI对象模型 OpenAPI规范文档的对象模型。 常问问题 这是做什么的？ 该软件包知道如何将Swagger API规范编组和解编成golang对象模型 它知道如何解析$ ref并将其扩展为单个根文档 它如何与其他go-openapi软件包一起使用？ 此软件包是go-openapi软件包和套件的核心 有一个，可从本地或远程位置以JSON或YAML的形式获取规范 有一个基于其的 在其之上构建了一个，用于分析，展平，修复和合并规范文档 该库是否支持OpenAPI 3？ 否。此软件包当前仅支持OpenAPI 2.0（又名Swagger 2.0）。 没有计划使其朝支持OpenAPI 3.x的方向发展。 该涉及整个故事。 支持Swagger 3的早期尝试可以在以下找到： ：
RESTAPI标准接口OpenAPI-Specification.zip
07-19
OpenAPI Specification 的目标是为 REST API 定义一个标准的、与语言无关的接口，允许人和计算机在不访问源代码、文档或通过网络的情况下发现和理解服务的功能。 通过 OpenAPI 的正确定义，消费者可以用最简答的方式理解远程服务并与其交互，消除了调用服务时的猜测。OpenAPI不需要重写现有的API。它不需要将任何软件绑定到服务，所描述的服务甚至可能不是您的。然而，它要求在 OpenAPI Specification 的结构中描述服务的能力。不是所有的服务都可以由 OpenAPI 描述 —— 此规范并不打算涵盖 REST-ful API 的每一个可能的用例。 OpenAPI没有规定诸如设计优先或代码优先的开发过程。它通过与 REST API 建立明确的交互来促进这两种技术之一。 标签：OpenAPI
探索OpenAPI Specification：构建可互操作的RESTful API的利器
gitblog_00069的博客
03-19 628
探索OpenAPI Specification：构建可互操作的RESTful API的利器 OpenAPI-SpecificationThe OpenAPI Specification Repository项目地址:https://gitcode.com/gh_mirrors/op/OpenAPI-Specification 是一个开放源代码项目，由OpenAPI Initiative (OAI...
OpenAPI 标准规范
ITMuch的专栏
08-25 1400
点击上方IT牧场，选择置顶或者星标技术干货每日送达！什么是API规范API 是模块或者子系统之间交互的接口定义。好的系统架构离不开好的 API 设计，而一个设计不够完善的 API ...
使用 OAS（OpenAPI标准）来描述 Web API
HuaZi_Myth的博客
01-20 820
无论哪种类型的Web API, 都可能需要给其他开发者使用. 所以API的开发者体验是很重要的. API的开发者体验, 简写为 API DX (Developer Experience). 它包含很多东西, 例如如何使用API, 文档, 技术支持等等, 但是最重要的还是API的设计. 如果 API 设计的不好, 那么使用该API构建的软件就需要增加在时间,人力,金钱等方面的投入. 有时候AP...
Go OpenAPI Spec 使用与安装教程
gitblog_00696的博客
09-05 382
Go OpenAPI Spec 使用与安装教程 specopenapi specification object model项目地址:https://gitcode.com/gh_mirrors/spec10/spec 欢迎来到Go OpenAPI Spec项目指南！本教程将引导您了解此开源项目的核心要素，包括其目录结构、启动文件以及配置文件的概览，旨在帮助您顺利地集成并利用这个强大的OpenA...
推荐开源项目：openapi-validator-middleware，保障你的API交互无懈可击
gitblog_00088的博客
06-14 389
推荐开源项目：openapi-validator-middleware，保障你的API交互无懈可击 项目地址:https://gitcode.com/gh_mirrors/op/openapi-validator-middleware 在开发现代Web应用和微服务架构中，API的设计与验证是确保系统稳定性和数据准确性的关键环节。今天，我们为你推荐一款强大的开源工具——openapi-validat...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值