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