[OpenAPI / YAML / JSON linting] Using Spectral, Redocly CLI, and Vacuum

.redocly.yml

# More info on Redocly config: https://redocly.com/docs/cli/configuration/
# Redocly API guidelines builder: https://redocly.com/api-governance/
# List of Redocly built-in linting rules: https://redocly.com/docs/cli/rules/built-in-rules/
# Redocly comparison to Spectral (another popular OpenAPI linter): https://redocly.com/docs/cli/guides/migrate-from-spectral/
apis:
  perks@v1:
    root: optum-perks-online-care-api-spec.yml
extends:
  - recommended-strict
rules:
  # -----------------------
  # Built-in Rules
  #
  # Note that these are in addition to the recommended-strict rules.
  # -----------------------
  boolean-parameter-prefixes:
    severity: error
    prefixes:
      - is
      - can
      - has
  component-name-unique: error
  no-ambiguous-paths: error
  no-http-verbs-in-paths:
    severity: error
    splitIntoWords: true
  no-invalid-schema-examples: error
  no-required-schema-properties-undefined: error
  operation-4xx-response: error
  operation-description: error
  operation-operationId: error
  operation-singular-tag: error
  operation-tag-defined: error
  parameter-description: error
  path-not-include-query: error
  path-segment-plural:
    severity: error
    ignoreLastPathSegment: true
    exceptions:
      - v1
      - v2
  paths-kebab-case: error
  response-contains-property:
    severity: error
    names:
      4xx:
        - message
  spec-strict-refs: error
  tags-alphabetical: error
  info-license: off          # Licensing for this API is not applicable
  no-server-example.com: off # This can be turned on once we decide on a base URL
  security-defined: off      # This can be turned on once we decide on security requirements

  # -----------------------
  # Custom Rules
  # -----------------------

  # "API" must be in document title
  rule/info-title-api:
    severity: error
    subject:
      type: Info
      property: title
    assertions:
      pattern: /.*API.*/

  # Require API description
  rule/info-description:
    severity: error
    subject:
      type: Info
      property: description
    assertions:
      defined: true

  # operationId must use camelCase
  rule/operationId-casing:
    severity: error
    subject:
      type: Operation
      property: operationId
    assertions:
      casing: camelCase

  # Parameters must use camelCase
  rule/parameter-casing:
    severity: error
    subject:
      type: Parameter
    assertions:
      casing: camelCase

  # Parameters must include examples
  rule/params-must-include-examples:
    severity: error
    subject:
      type: Parameter
    assertions:
      required:
        - examples

  # Schemas must include type
  rule/schemas-must-include-type:
    severity: error
    subject:
      type: Schema
    assertions:
      required:
        - type

  # Named schemas must use PascalCase
  rule/schema-name-casing:
    severity: error
    subject:
      type: NamedSchemas
    assertions:
      casing: PascalCase

  # Schema property names must use camelCase
  rule/schema-property-casing:
    severity: error
    subject:
      type: SchemaProperties
    assertions:
      casing: camelCase

  # Headers must include examples
  rule/headers-must-include-examples:
    severity: error
    subject:
      type: Header
    assertions:
      required:
        - examples

  # Tags must include descriptions
  rule/tag-description:
    severity: error
    subject:
      type: Tag
      property: description
    assertions:
      defined: true

  # No periods at the end of a summary
  rule/no-summary-period:
    severity: error
    subject:
      type: any
      property: summary
    assertions:
      pattern: /[^.]$/
    message: No periods at the end of a summary.

  # Operations must include tags
  rule/operation-must-include-tag:
    severity: error
    subject:
      type: Operation
    assertions:
      required:
        - tags

  # Summaries must start with a capital letter
  rule/summary-capitalization:
    severity: error
    subject:
      type: Operation
      property: summary
    assertions:
      pattern: /^[A-Z]/
    message: Summaries must start with a capital letter.

  # Descriptions must start with a capital letter
  rule/description-capitalization:
    severity: error
    subject:
      type: any
      property: description
    assertions:
      pattern: /^[A-Z#]/
    message: Descriptions must start with a capital letter.

  # Tag descriptions must end with a period
  rule/tag-description-period:
    severity: error
    subject:
      type: Tag
      property: description
    assertions:
      pattern: /[.]$/
    message: Tag descriptions must end with a period.

  # Must include examples at the schema level
  # NOTE: Nothing stopping us from adding examples at the property level as well. Just keep in mind that property
  #       level examples will override schema level examples.
  rule/schemas-must-include-examples:
    severity: error
    subject:
      type: Schema
      property: examples
    where:
      - subject:
          type: NamedSchemas
        assertions:
          defined: true
    message: Must include examples at the schema level.
    assertions:
      defined: true
      nonEmpty: true

  # Use "examples" keyword instead of "example"
  rule/disallow-keyword-example:
    severity: error
    subject:
      type: any
      filterOutParentKeys:
        -  properties
        -  parameters
    message: Keyword "example" has been deprecated. Use keyword "examples" instead.
    assertions:
      disallowed:
        - example

  # Path items must be defined in a separate file using $ref
  rule/path-item-defined-separately:
    severity: error
    subject:
      type: PathItem
    assertions:
      ref: true
    message: 'Path items must be defined in a separate file using $ref.'

  # Schema items must be defined in a separate file using $ref
  rule/schema-item-defined-separately:
    severity: error
    subject:
      type: Schema
    where:
      - subject:
          type: NamedSchemas
        assertions:
          defined: true
    assertions:
      ref: true
    message: 'Schema items must be defined in a separate file using $ref.'

  # Parameter items must be defined in a separate file using $ref
  rule/parameter-item-defined-separately:
    severity: error
    subject:
      type: Parameter
    where:
      - subject:
          type: NamedParameters
        assertions:
          defined: true
    assertions:
      ref: true
    message: 'Parameter items must be defined in a separate file using $ref.'

lint_openapi.sh

# Spectral
# make sure to update the value of `--ruleset` according to the actual location of your ruleset
docker run --rm -it -v $PWD:/tmp stoplight/spectral lint --ruleset "/tmp/.spectral.yml" "/tmp/<spec-file.yml>"

# Redocly CLI
docker run --rm -v $PWD:/spec redocly/cli lint <spec-file.yml>

# Vacuum
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint -d <spec-file.yml>