# path-parameters-on-items

Source: https://api-genie.dev/docs/linter/swagger/rules/path-parameters-on-items

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. Since 0.9.0. In the rulesets: Recommended at warning, Strict at warning, All at error.

This rule checks whether path parameters are declared on path items rather
than on individual operations.

## Rule details

A path parameter belongs to the path, so every operation of a path item shares
it. Declaring it once in the `parameters` of the path item avoids repeating
the same definition in every operation and keeps the definitions consistent.

The `path-parameters-on-items` rule reports `One or more path parameters are
missing or not defined in path item` for every path item when a template
expression of its path has no matching `in: path` parameter in the path
item's own `parameters`. Parameters declared on operations do not count.
Parameter references (`$ref`) are resolved.

The OpenAPI linter has a rule of the same name,
[path-parameters-on-items](/docs/linter/openapi/rules/path-parameters-on-items), for OpenAPI 3.x
documents.

Turn the rule off if your style guide prefers declaring path parameters on operations.

## Examples

**Good**. The path parameter is declared on the path item.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{petId}:
    parameters:
      - $ref: '#/parameters/petId'
    get:
      responses:
        '200':
          description: A single pet.
parameters:
  petId:
    name: petId
    in: path
    required: true
    type: string
```

**Bad**. The path parameter is declared on the operation.

```yaml
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.
```
