Linter rulesSwagger 2.0swagger-validation

swagger-validation

Since 0.9.0

This rule reports violations of the Swagger 2.0 specification that span several objects, and therefore cannot be detected while a single object is read.

Rule Details

The reader checks the structure of every object of a document, but some requirements of the specification relate several objects to each other: a security requirement must name a declared security definition, a path parameter must appear in its path template, and so on. The swagger-validation rule runs these checks:

Check Requirement
unique-operation-id operationId values are unique across the document
unique-parameter (name, in) pairs are unique within a parameter list
single-body-parameter an operation has at most one body parameter
body-form-data-exclusive body and formData parameters are not mixed
file-parameter-consumes file parameters require multipart/form-data or application/x-www-form-urlencoded in consumes; other formData parameters are reported when consumes lists neither
path-parameter-declared every path template variable has a path parameter
path-parameter-in-template every path parameter appears in the path template
security-scheme-defined security requirements refer to securityDefinitions
security-scope-defined oauth2 requirements use declared scopes
security-scopes-empty requirements of other schemes have empty scope lists
unresolved-reference local references (#/definitions, #/parameters, #/responses) resolve
valid-scheme schemes are http, https, ws or wss
host-format host contains neither a scheme nor a path
unique-tag tag names are unique
discriminator-required a discriminator property is listed in required

Each message is the message of the check, followed by the check name in parentheses, for example An operation can have at most one body parameter (single-body-parameter) or Unresolved reference '#/definitions/Missing' (unresolved-reference). All issues are reported with the severity of this rule.

By default all checks run except unique-operation-id, unique-parameter, path-parameter-declared and unique-tag. These are covered by the dedicated rules operation-id-unique, parameters-unique, path-parameters-defined and tags-unique, which can also fix some of the issues.

Configuration

The rule accepts an object with one option:

  • checks: the names of the checks to run. The list replaces the default set of checks, so include every check you want. Unknown names are rejected.

Configuration Example. Run all checks, including those of the dedicated rules (which you would then disable).

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        swagger-validation:
          - error
          - checks:
              - unique-operation-id
              - unique-parameter
              - single-body-parameter
              - body-form-data-exclusive
              - file-parameter-consumes
              - path-parameter-declared
              - path-parameter-in-template
              - security-scheme-defined
              - security-scope-defined
              - security-scopes-empty
              - unresolved-reference
              - valid-scheme
              - host-format
              - unique-tag
              - discriminator-required

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: api.example.com
schemes: [https]
paths:
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: The pet.

Bad. The host includes a scheme, ftp is not a valid scheme, the security requirement names an undeclared security definition, the operation has two body parameters, and one of them refers to a missing definition.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: https://api.example.com
schemes: [ftp]
paths:
  /pets:
    post:
      parameters:
        - name: a
          in: body
          schema:
            $ref: '#/definitions/Missing'
        - name: b
          in: body
          schema:
            type: object
      security:
        - unknown: []
      responses:
        '200':
          description: OK

When Not to Use It

We recommend to always enable this rule: documents that violate these requirements are not valid Swagger 2.0 documents, and tools may reject them or misinterpret them.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, whose openapi-json-schema-validation rule validates them against the OpenAPI 3.x JSON schema.

Related rules

Further reading