path-parameters-on-items

This rule ensures that all path parameters are defined on path item levels, and not on the operation level.

Rule Details

Defining path parameters as children of path items, and not operations helps to maintain consistency and clarity in the API’s structure, as well as to avoid duplicate parameter definitions.

The path-parameters-on-items rule is designed to ensure that all path parameters are defined on path item levels, rather than on the operation level.

Configuration

None.

Examples

Good.

paths:
    /users/{userId}:
        parameters:
        - name: userId
            in: path
            required: true
            schema:
                type: string
        get:
            summary: Get a user by ID

Bad. Definition of the userId parameter has to be duplicated in all operations.

paths:
    /users/{userId}:
        get:
            summary: Get a user by ID
            parameters:
            - name: userId
                in: path
                required: true
                schema:
                    type: string
        delete:
            summary: Delete a user by ID
            parameters:
            - name: userId
                in: path
                required: true
                schema:
                    type: string

When Not to Use It

If your API does not use path parameters or if you have other means of ensuring that parameters are defined at the correct level, you may not need to use this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.