description-duplication

Descriptions are really important. Often, contract authors copy and paste a lot. This it because it’s easier to copy and paste things and modify them, rather than typing out a bunch of YAML or JSON.

The problem with copy and pasting for contracts should be clear. Duplication of content is everywhere, including descriptions. This is really un-helpful for anyone trying to understand a contract, not to mention creating a really poor experience for documentation users.

This rule checks that no two descriptions are the same.

Why did this violation appear?

One or more description elements in the spec are identical.

Bad example

paths:
  /chicken/nuggets/{nuggetId}:
    get:
      description: "Get a chicken nugget by ID"
      ...
components:
  schemas:
    ChickenNugget:
      description: "Get a chicken nugget by ID"

Good example

paths:
  /chicken/nuggets/{nuggetId}:
    get:
      description: "Get a chicken nugget by ID"
      ...
components:
  schemas:
    ChickenNugget:
      description: "Represents a chicken nugget as an object"

How do I fix this violation?

Make sure every description is unique and meaningful. Descriptions really are the most important part of a spec.

Spectral Equivalent

There is no spectral equivalent. This rule is unique to vacuum.