Reference to parameter object within path item object is marked as invalid in swagger editor

Author: k-riscCreated Feb 23, 2026Updated Feb 23, 2026

As a result of #162, common paginator parameters are now referenced. Their definition resides under x-swagger-bake/components/parameters.

When validating a swagger file containing such references, the swagger editor complains: "OAS3 parameter $Ref should point to Parameter Object" Image

If I manually move or copy the parameter definition to components/parameters and change the $ref path to the new location, the editor does not complain any more: Image

I can also change the new definition under components/parameters to be itself a reference and to point to the concrete definition under x-swagger-bake/components/parameters. That validates as well.

According to the OpenAPI specification, references for such parameters should be defined in components/parameters: Image

Thus, can the definition under x-swagger-bake/components/parameters (and referencing those definitions directly from path items) be valid under any circumstances?

Source: swagger-api/swagger-editor