Solución:
No es compatible con la especificación 2.0 y tampoco con la 3.0.
Aquí están las propuestas correspondientes en el repositorio de especificaciones de OpenAPI:
Adapte las API heredadas al permitir parámetros de consulta en la ruta
Cadena de consulta en la especificación de ruta
Si todavía está buscando, descubrí una forma de solucionar este problema. Es un truco, pero funciona.
Básicamente, puede tener dos definiciones en la misma ruta agregando una barra (/) en la URL.
De esa forma, puede establecer una respuesta para <baseURL>/path con el ?filter1= parámetro y establezca otra respuesta para <baseURL>//path con el ?filter2= parámetro. También es importante que le des una operationId para cada una de las definiciones.
paths:
/path/you/want:
get:
summary: Test
operationId: get1
parameters:
- name: filter1
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
/path/you//want:
get:
summary: Another test
operationId: get2
parameters:
- name: filter2
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeOtherResponse'
¡Intenté esto con un parámetro de ruta y funcionó bien!