no-dup-paths.md

each API path should be unique (no-dup-paths)

All API paths in a Swagger specification should be unique.

Uniqueness is not only based on verbatim equality, but also functional equivalency.

⤴️ Back to Rules README

Table of contents

• Table of contents
• Rule Details
  • Examples of incorrect code for this rule
  • Examples of correct code for this rule
• When Not To Use It
• Version
• Further Reading

Rule Details

This rule aims to ensure that API paths are literally and functionally unique.

Examples of incorrect code for this rule

{
  "paths": {
    "/pets/{id}": ...,
    "/pets/{id}": ...,
    "/pets/{chipId}": ...,
    "/pets/{petId}": ...,
    "/pets/{uuid}": ...
  }
}

Examples of correct code for this rule

{
  "paths": {
    "/pets/{petId}": ...
  }
}

When Not To Use It

⚠️ This rule should always be enabled.

In cases where your API path has a param that needs functional distinction, add a query input qualifier, e.g.,

GET /pets/{id}?idType=aaha
GET /pets/{id}?idType=petlink

For identifiers, create a UUID and create a model called RegisteredId that provides identifier semantics (if possible):

GET /pets/{uuid}/registeredIds

Returns:

[
  {
    "id": "11111111",
    "type": "aaha",
    "registrationAuthority": "American Animal Hospital Association",
    "validFrom": 1326261600000,
    "validTo": null
  },
  {
    "id": "22222222",
    "type": "petlink",
    "registrationAuthority": "Datamars",
    "validFrom": 1326261600000,
    "validTo": null
  }
]

Version

The no-dup-paths rule was introduced to eslint-plugin-swagger in version 0.1.0.

Further Reading

• Rule source
• Rule specs
• Documentation source

---

⤴️ Back to Rules README