

Rules

naming

Check for consistent naming conventions within components of the spec.

The supported naming conventions are:

• PascalCase
• CamelCase
• KebabCase
• SnakeCase

rules:
  naming:
    paths: KebabCase
    tags: PascalCase
    operation: CamelCase
    parameters: SnakeCase
    definitions: PascalCase
    properties: camelCase

noEmptyDescriptions

Disallows empty descriptions for various components of the spec.

A value of true will cause empty or missing descriptions to become errors. false or omitted will allow empty descriptions.

rules:
  noEmptyDescriptions:
    operations: true
    properties: true
    parameters: false

noEmptyOperationIDs

Disallows empty operation IDs

Example

rules:
  noEmptyOperationIDs: true

Good

paths:
  /pets:
    get:
      operationId: listPets
      ...

Bad

paths:
  /pets:
    get:
      operationId: ""
      ...

slashTerminatedPaths

Check that paths consistently end with a slash or not.

A value of true requires paths to end in a slash. A value of false will require all paths to not end with a slash.

Example

rules:
  slashTerminatedPaths: true

Good

paths:
  /pets/:
    ...

Bad

paths:
  /pets:
    ...

noEmptyTags

Check that all operations have at least 1 non-empty tag

Example

rules:
  noEmptyTags: true

Good

paths:
  /pets/:
    get:
      tags:
        - pets
      ...

Bad

paths:
  /pets/:
    get:
      tags: []
      ...

noUnusedDefinitions

Disallows definitions that aren't used anywhere

Example

rules:
  noUnusedDefinitions: true

Good

paths:
  /pets/:
    responses:
      200:
        schema:
          $ref: '#/definitions/User'

definitions:
  User:
    type: object
      ...

Bad

paths:
  /pets/:
    responses:
      200:
        schema:
          type: object

definitions:
  User:
    type: object

noDuplicateOperationIDs

Disallows duplicate operation IDs.

Example

rules:
  noDuplicateOperationIDs: true

Good

paths:
  /pets/:
    operationId: listPets
  /pets/{id}/:
    operationId: getPet

Bad

paths:
  /pets/:
    operationId: listPets
  /pets/{id}/:
    operationId: listPets

noMissingRequiredProperties

Disallows properties from being listed as "required" without being defined under "properties" of a schema.

Example

rules:
  noMissingRequiredProperties: true

Good

definitions:
  User:
    type: object
    required:
      - id
      - username
    properties:
      id:
        type: string
      username:
        type: string

Bad

definitions:
  User:
    type: object
    required:
      - id
      - username
    properties:
      username:
        type: string