New rules ideas #35
Description
Version in semver
openapi-v3-info-version-semver:
description: API Definitions SHOULD following semver.
severity: warn
message: >-
Definitions SHOULD follow semantic versioning. {{value}} is not a valid
version.
given: $.info.version
then:
function: pattern
functionOptions:
match: '^([0-9]+.[0-9]+.[0-9]+)$'
No mime types in paths
openapi-v3-path-includes-mime:
description: Paths MUST NOT end mime types such as .json and .xml.
severity: error
message: >-
Paths MUST NOT end with mime types such as .json and .xml.
Use response types.
given: $.paths[*]~
then:
function: pattern
functionOptions:
notMatch: ".(\.json|\.xml|\.html|\.txt)$"
Path param names represent the resource
openapi-v3-path-parameter-ambiguous:
description: |-
All path parameters should be named after the resource they represent.
Rather than calling them just 'id', we should use more meaningful names
like 'employeeId' for '/employees' resource.
Calling a path parameter "id" will need rework when any sub resources are
added.
severity: warn
message: >-
Path Parameters SHOULD NOT be named {{value}}, they SHOULD be named after
the resource they represent, i.e. 'employeeId' for '/employees' to avoid
conflicts with sub resources in the future.
given: $..parameters[?(@.in == 'path')]
then:
field: name
function: pattern
functionOptions:
notMatch: '\b(id|Id|ID|iD)\b'
Components have names valid with openAPI spec
openapi-v3-styling-component-names-valid-with-spec:
description: >-
All component name MUST consist of the following characters only:
A..Z a..z 0..9 . _ -
severity: error
message: >-
component name: {{property}} is not a valid name. All component name MUST
consist of the following characters only: A..Z a..z 0..9 . _ -
given:
- $.components.schemas[]~
- $.components.parameters[]~
- $.components.securitySchemes[]~
- $.components.requestBodies[]~
- $.components.responses[]~
- $.components.headers[]~
- $.components.examples[]~
- $.components.links[]~
- $.components.callbacks[*]~
then:
function: pattern
functionOptions:
match: '^[a-zA-Z0-9._-]+$'
Dont use http method names in paths
openapi-v3-styling-operation-avoid-http-operation-name:
description: >-
Operation SHOULD not use HTTP method as part of its name.
severity: warn
type: 'style'
given: $.paths[*]~
message: >-
Operation {{property}} SHOULD not use a HTTP method as part of its name.
then:
function: pattern
functionOptions:
notMatch: >-
/(?:\b)(get|put|post|patch|options|head|trace|update|delete|create|list)(?:\b)/i
*Request bodies required
openapi-v3-request-bodies-required:
description: >-
Every request body SHOULD be required.
severity: warn
message: All request bodies SHOULD be required.
given: '$.paths.[*].requestBody'
then:
- field: 'required'
function: truthy
Request bodies not allowed on GET
openapi-v3-get-request-body-should-not-exist:
description: >-
GET operations SHOULD NOT have a requestBody. See RFC7231 for more
information. Sending a payload body on a GET request might cause some
existing implementations to reject the request.
message: >-
{{path}} is a GET operation with a requestBody. GET operations SHOULD NOT
have a requestBody. See RFC7231 for more information.
severity: warn
given: $.paths.[get].requestBody
then:
function: undefined