paths-unique

Since 0.9.0 · In the rulesets: Strict at error, All at error

This rule checks whether a Swagger 2.0 document defines paths that are equivalent to each other.

Rule details

Paths such as /pets/{id} and /pets/{petId} differ only by the names of their template expressions, so they match exactly the same requests. Tools cannot tell which path item a request belongs to.

The paths-unique rule normalizes every path by replacing each template expression with {}, collapsing repeated slashes and removing a trailing slash, and reports Duplicate path found on every path item whose normalized path equals the normalized path of an earlier one. Paths are compared case-sensitively.

The OpenAPI linter has a rule of the same name, paths-unique, for OpenAPI 3.x documents.

Examples

Good. The paths match different requests.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: A single pet.
  /pets/{petId}/toys:
    get:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: The toys of a pet.

Bad. Both paths match the same requests.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: A single pet.
  /pets/{petId}/:
    delete:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The pet was deleted.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        paths-unique: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?