Agent Testing
FAQ
Autofix

  • GitHub GitHub Repo stars
  • Discord Discord Server
  • 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 path templates across HTTP methods
    • Duplicate parameter names in paths
    • Unknown (un-named) parameters
    • Compliance with ‘required’ state
    • All parameters must be defined

    Bad examples

    These paths have equivalent templates, even though their HTTP methods differ.

    paths:
      /pets/{id}:
        parameters:
          - {name: id, in: path, required: true, schema: {type: string}}
        get:
          responses:
            '200': {description: Pet found}
      /pets/{name}:
        parameters:
          - {name: name, in: path, required: true, schema: {type: string}}
        delete:
          responses:
            '204': {description: Pet deleted}
    

    Changed in v0.42.0

    In v0.41.0 and earlier, equivalent path templates were allowed when their HTTP methods differed.

    From v0.42.0, path-params reports an error for equivalent templates across methods, with one finding per duplicate path. For example, GET /pets/{id} and DELETE /pets/{name} conflict. Put both operations under one path and use the same parameter name.

    Good example

    Put both operations under one path and use the same parameter name.

    paths:
      /pets/{id}:
        parameters:
          - {name: id, in: path, required: true, schema: {type: string}}
        get:
          responses:
            '200': {description: Pet found}
        delete:
          responses:
            '204': {description: Pet deleted}
    

    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