OpenAPI V3 Spec validation tools
Project structure
- oas-validator-core: core apis and skeletons implementations
- oas-validator-core-spring: Spring Boot Starter for core skeletons
- oas-validator-test: test helpers for core api
- oas-validator-compliance: check style validators
- oas-validator-compliance-spring: Spring Boot Starter for check style validators
- oas-validator-compatibility: compatibility validators
- oas-validator-compatibility-spring: Spring Boot Starter for compatibility validators
- oas-validator-web: web ui
Style check rules
OAS must compatible with OAS 3.0.2, besides must obey the following rules.
String patterns
- Lower Camel Case: initial letter lowercase camel case, regex is
^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$
- Upper Camel Case: initial letter uppercase camel case, regex is
^[A-Z]([a-z0-9]+[A-Z]?)*$
- Upper Hyphen Case: initial letter uppercase, multiple words concat with
-
, such asContent-Type
,Accept
,X-Rate-Limit-Limit
, regex is^([A-Z][a-z0-9]*-)*([A-Z][a-z0-9]*)$
OpenAPI Object doc
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 provide
Info Object doc
description
property, required
Tag Object doc
name
property, must be Upper Camel Casedescription
property, required- Every tag should be referenced by at least one Operation Object
Paths Object doc
- path must be Lower Camel Case, including Path Templating variable
Path Item Object doc
get/post/put/delete/...
properties, see Operation Object style check rulesparameters
property, see Parameter Object style check rules
Operation Object doc
summary
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 Objecttags
propertyservers
property, should not provide
Parameter Object doc
description
property, requiredname
property- if
in
is path, query or cookie, then must be Lower Camel Case - if
in
is header, then must be Upper Hyphen Case
- if
schema
property, see Schema Object check sytle rulescontent
property, see Media Type Object style check rules
Request Body Object doc
description
property, requiredcontent
property, see Media Type Object style check rules
Media Type Object doc
schema
property, required. See Schema Object style check rulesencoding
property, see Encoding Object style check rules
Responses Object doc
Response Object doc
description
property, requiredheaders
property, name (headers
key) must be Upper Hyphen Casecontent
property, see Media Type Object style check rules
Schema Object doc
title
property, required if parent is Schema Object or Components Objectproperties
property, name(properties
key) must be Lower Camel Case- Sub Schema, see Schema Object style check rules
Encoding Object doc
headers
property, name(headers
key) must be Upper Hyphen Case
Header Object doc
description
property, requiredschema
property, see Schema Object style check rulescontent
property, see Media Type Object style check rules
Components Object doc
schemas
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 Case
Compatibility check rules
Check 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.
Paths Object doc
- New OAS must include all the
path
appears in 旧OAS. Ifpath
uses Path Templating, even the variable name changed, will be considered semantically different. For example/pets/{foo}
and/pets/{bar}
are different.
Path Item Object doc
- New OAS must inclued all old OAS get/put/post/delete/…Operation Object
Operation Object doc
operationId
property, new and old must be identicalparameters
property, check work must also consider Path Item Object parameters property:- New OAS could add new Parameter Object, but the new Parameter Object
required
property must befalse
- New OAS could deleteParameter Object
- The check on Parameter Object see Parameter Object compatibility check rules(Under the same Operation Object Parameter Object is identified by
name
andin
property)。
- New OAS could add new Parameter Object, but the new Parameter Object
requestBody
property, see Request Body Object compatibility check rulesresponses
property, seeResponses Object compatibility check rules
Parameter Object doc
required
property, only allowtrue(old) -> false(new)
changeallowEmptyValue
property, only allowfalse(old) -> true(new)
changestyle
property, new and old must be identicalexplode
property, new and old must be identicalallowReserved
property, only allowfalse(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 allowed
Request Body Object doc
content
property, new OAS must include all old OAS media type (content
keys)required
property, only allowtrue(old) -> false(new)
change
Media Type Object doc
schema
property, see Schema Object compatibility check rulesencoding
property, this property only apply torequestBody
, so new OAS and old OAS property name(encoding
key) must be identical
Responses Object doc
default
property, if old OAS doesn’t definedefault
, then new OAS should not definedefault
too.{Http Status Code}
property, new OAS is not allowed to add one.- See Response Object compatibility check rules
Response Object doc
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 allowed
Schema Object doc
OAS allows Schema Object be directly or indirectly in:
- Request: Parameter Object, Request Body Object, Header Object
- Response: Header Object, Response Object
In different context compatibility check rules are different.
In request context
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 changetrue(old)->false(new)
uniqueItems
property, only allow changetrue(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 changefalse(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 identical
In response context
When 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 changefalse(old)->true(new)
uniqueItems
property, only allow changefalse(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 changetrue(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 identical
Encoding Object doc
Notice: 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 changefalse(old) -> true(new)
Header Object doc
schema
property, see Schema Object compatibility check rules
Components Object doc
Components Object defines reusable OAS Object, but when doing compatibility check all $ref
are resolved, so no need to check Components Object compatibility.