Linter rulesSwagger 2.0paths-unique

paths-unique

Since 0.9.0

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.

Configuration

None.

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.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading