# swagger-validation

Source: https://apigenie.pl/docs/linter/swagger/rules/swagger-validation

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).

```yaml
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**.

```yaml
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.

```yaml
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.