FAQ

  • GitHub GitHub Repo stars
  • Discord Discord Server
  • ✨ New! Try the OpenAPI Doctor ✨ The OpenAPI Doctor
    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