OpenAPI V3 Spec validation tools.
OAS must compatible with OAS 3.0.2, besides must obey the following rules.
^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$
^[A-Z]([a-z0-9]+[A-Z]?)*$
-
, such as Content-Type
, Accept
, X-Rate-Limit-Limit
, regex is ^([A-Z][a-z0-9]*-)*([A-Z][a-z0-9]*)$
openapi
property must be 3.0.x and >= 3.0.2info
propety, see Info Object style check rulespaths
property, must provide, see Paths Object style check rulescomponents
property, see Components Object style check rulestags
property should at least provide one Tag Objectsecurity
property, should not providedescription
property, requiredname
property, must be Upper Camel Casedescription
property, requiredget/post/put/delete/...
properties, see Operation Object style check rulesparameters
property, see Parameter Object style check rulessummary
property, requiredoperationId
property, must be Lower Camel Caseparameters
property, see Parameter Object style check rulesrequestBody
property, see Request Body Object style check rulesresponses
property, see Responses Object style check rulestags
property, can only provide one tag, must be in the range of OpenAPI Object tags
propertyservers
property, should not providedescription
property, requiredname
propertyin
is path, query or cookie, then must be Lower Camel Casein
is header, then must be Upper Hyphen Caseschema
property, see Schema Object check sytle rulescontent
property, see Media Type Object style check rulesdescription
property, requiredcontent
property, see Media Type Object style check rulesschema
property, required. See Schema Object style check rulesencoding
property, see Encoding Object style check rulesdescription
property, requiredheaders
property, name (headers
key) must be Upper Hyphen Casecontent
property, see Media Type Object style check rulestitle
property, required if parent is Schema Object or Components Objectproperties
property, name(properties
key) must be Lower Camel Caseheaders
property, name(headers
key) must be Upper Hyphen Casedescription
property, requiredschema
property, see Schema Object style check rulescontent
property, see Media Type Object style check rulesschemas
property, name must be Upper Camel Caseresponses
property, name must be Upper Camel Caseparameters
property, name must be Upper Camel Caseexamples
property, name must be Upper Camel CaserequestBodies
property, name must be Upper Camel Caseheaders
property, name must be Upper Hyphen Caselinks
property, name must be Upper Camel Casecallbacks
property, name must be Upper Camel CaseCheck whether new OAS spec compatibile with old spec.
Notice: OAS could use Reference Object, two OAS which are different in text maybe semantically same. For example, below old OAS doesn't use Reference Object while the new one uses:
Old OAS
openapi: "3.0.0" info: version: 1.0.0 title: Swagger Petstore license: name: MIT servers: - url: http://petstore.swagger.io/v1 paths: /pets: post: summary: List all pets operationId: listPets requestBody: content: application/json: schema: type: array items: type: object properties: Foo: type: string responses: '200': description: A paged array of pets
New OAS
paths: /pets: post: operationId: listPets requestBody: content: application/json: schema: $ref: '#/components/schemas/Foo' responses: '200': description: A paged array of pets components: schemas: Foo: type: array items: type: object properties: Foo: type: string
So, when do compatibility check we resolve Reference Object in old and new OAS first, then do the check, below is the code snippet using swagger-parser:
OpenAPIV3Parser parser = new OpenAPIV3Parser(); ParseOptions parseOptions = new ParseOptions(); parseOptions.setResolve(true); parseOptions.setResolveCombinators(true); parseOptions.setResolveFully(true); parseOptions.setFlatten(false); SwaggerParseResult parseResult = parser.readContents(content, null, parseOptions);
So if compatibility violations be found, the reported location will be different from the location in origin OAS spec.
path
appears in 旧OAS. If path
uses Path Templating, even the variable name changed, will be considered semantically different. For example /pets/{foo}
and /pets/{bar}
are different.operationId
property, new and old must be identicalparameters
property, check work must also consider Path Item Object parameters property:required
property must be false
name
and in
property)。requestBody
property, see Request Body Object compatibility check rulesresponses
property, seeResponses Object compatibility check rulesrequired
property, only allow true(old) -> false(new)
changeallowEmptyValue
property, only allow false(old) -> true(new)
changestyle
property, new and old must be identicalexplode
property, new and old must be identicalallowReserved
property, only allow false(old) -> true(new)
changeschema
property, see Schema Object compatibility check rulescontent
property, new OAS must include all old OAS media type (content
keys), and add new media type is not allowedcontent
property, new OAS must include all old OAS media type (content
keys)required
property, only allow true(old) -> false(new)
changeschema
property, see Schema Object compatibility check rulesencoding
property, this property only apply to requestBody
, so new OAS and old OAS property name(encoding
key) must be identicaldefault
property, if old OAS doesn't define default
, then new OAS should not define default
too.{Http Status Code}
property, new OAS is not allowed to add one.headers
property, new OAS must include all old OAS header name(headers
keys), and add new header name is allowedcontent
property, new OAS must include all old OAS media type(content
keys), and add new media type is allowedOAS allows Schema Object be directly or indirectly in:
In different context compatibility check rules are different.
When Schema Object is in response context, only allow change from more specific form to less specific form.
type, format
combination allowed change:Old (type,format) | New (type,format) |
---|---|
integer, null | integer, int64 number, double number, null |
integer, int32 | integer, int64 integer, null number, float number, double number, null |
integer, int64 | integer, null number, double number, null |
number, null | number, double |
number, float | number, null number, double |
number, double | number, null |
string, null | string, password |
string, password | string, null |
allOf
, oneOf
, anyOf
property, combine them first then do checkmultipleOf
property, if old OAS is null, then new OAS must == old OAS or new OAS is a factor of old OAS, eg, 6(old)->3(new)maximum
, maxLength
, maxItems
, maxProperties
, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be >= old OASminimum
, minLenght
, minItems
, minProperties
, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be <= old OAS.exclusiveMaximum
, exclusiveMinimum
property, only allow change true(old)->false(new)
uniqueItems
property, only allow change true(old)->false(new)
required
property, new OAS must == old OAS or new OAS is old OAS subsetenum
property, new OAS must == old OAS or new OAS is old OAS supersetproperties
property, new OAS could add or delete property name(properties
key)nullable
property, only allow change false(old)->true(new)
discriminator
property, new and old must be identicalxml
property, new and old must be identicalreadOnly
, writeOnly
property, new and old must be identicalWhen Schema Object is in response context, only allow change from less specific form to more specific form.
type, format
combination allowed change:Old (type,format) | New (type,format) |
---|---|
integer, null | integer, int64 integer, int32 |
integer, int64 | integer, null interger, int32 |
number, null | number, double number, float |
number, double | number, null number, float |
string, null | string, password |
string, password | string, null |
allOf
, oneOf
, anyOf
property, combine them first then do checkmultipleOf
property if old OAS is null. new OAS must == old OAS or new OAS must be a multiple of old OAS, eg, 3(old)->6(new)maximum
, maxLength
, maxItems
, maxProperties
, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must <= old OASminimum
, minLenght
, minItems
, minProperties
, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must >= old OASexclusiveMaximum
, exclusiveMinimum
property, only allow change false(old)->true(new)
uniqueItems
property, only allow change false(old)->true(new)
required
new OAS must == old OAS or new OAS is old OAS supersetenum
property, new OAS must == old OAS or new OAS is old OAS subsetproperties
property, new OAS could add or delete property name(properties
key)nullable
property , only allow change true(old)->false(new)
discriminator
property, new and old must be identicalxml
property, new and old must be identicalreadOnly
, writeOnly
property, new and old must be identicalNotice: Encoding Object only apply to Request Body Object
contentType
property, new and old must be identicalheaders
property, new OAS can not add new he header name (headers
key), but and delete header namestyle
property, new and old must be identicalexplode
property, new and old must be identicalallowReserved
property, only allow change false(old) -> true(new)
schema
property, see Schema Object compatibility check rulesComponents Object defines reusable OAS Object, but when doing compatibility check all $ref
are resolved, so no need to check Components Object compatibility.