Recommended

path-params

Formats:

Severity:

Path Parameters are pretty easy to get wrong.

Sometimes, they can be defined, but never used, or used but never defined. Sometimes they are duplicated, or set to required, but then are not defined.

There is a whole raft of issues that can appear with Path Parameters, so this rule is one of the more complex ones.

Why did this violation appear?

An operation has used path parameters, but has incorrectly implemented them.

What is this rule checking for?

Unique paths (no duplicate parameters)
Duplicate parameter names in paths
Unknown (un-named) parameters
Compliance with ‘required’ state
All parameters must be defined

Bad examples

Duplicate paths (different param names, but conflicting path definitions)

 paths:
  /pizza/{cake}/{icecream}:
    parameters:
      - in: path
        name: cake
    get:
      parameters:
        - in: path
          name: icecream
  /pizza/{soda}/{candy}:
    parameters:
      - in: path
        name: soda
    get:
      parameters:
        - in: path
          name: candy  
          ...

Missing parameters (in path, but not defined)

paths:
  /pizza/{type}/{toppings}:
    parameters:
      - in: path
        name: type
    get:
      '200':
        ...

Using invalid required type

paths:
 /musical/{melody}/{beats}:
   parameters:
       - in: path
         name: melody
         required: NOT_VALID_SHOULD_BE_BOOL
   get:
     parameters:
       - in: path
         name: beats
         required: true

Parameter has been defined multiple times

paths:
 /musical/{melody}/{beats}:
   parameters:
       - in: path
         name: melody
       - in: path
         name: melody
   get:
     parameters:
       - in: path
         name: beats
       - in: path
         name: beats

How do I fix this violation?

Ensure all path params are used, they are unique and accounted for.

Spectral Equivalent

The rule is equivalent to path-params