Cómo definir un path param opcional en Swagger
En Swagger, los parámetros de ruta (path parameters) se utilizan para capturar valores en la URL, como identificadores o nombres de recursos. Sin embargo, todos los parámetros definidos en la ruta son obligatorios de manera predeterminada. Para definir un parámetro de ruta como opcional, es necesario modificar la estructura de la API. Una solución común es definir diferentes rutas que representen la variación con y sin el parámetro opcional.
Parámetros de ruta en Swagger
En Swagger/OpenAPI, los parámetros de ruta se definen dentro de la sección parameters de cada endpoint y se marcan con in: path. A continuación se muestra un ejemplo básico de un parámetro de ruta obligatorio:
paths:
/users/{userId}:
get:
summary: "Obtiene un usuario por ID"
parameters:
- name: "userId"
in: "path"
required: true
schema:
type: "string"Opcionalidad de los Path Parameters
Swagger no permite directamente marcar un parámetro de ruta como opcional, ya que la estructura de la URL debe coincidir exactamente con el patrón definido. En lugar de ello, es recomendable crear dos rutas separadas:
1. Ruta con parámetro: Definida con el path param.
2. Ruta sin parámetro: Definida sin el path param.
Por ejemplo:
paths:
/users:
get:
summary: "Obtiene la lista de usuarios"
parameters: []
/users/{userId}:
get:
summary: "Obtiene un usuario específico por ID"
parameters:
- name: "userId"
in: "path"
required: true
schema:
type: "string"Ejemplos de uso
1. Obtener todos los usuarios:
-
Ruta:
/users - Descripción: Recupera la lista de todos los usuarios registrados.
2. Obtener un usuario por ID:
-
Ruta:
/users/{userId} -
Descripción: Obtiene información detallada de un usuario específico usando su
userId.
Referencia oficial
Para más detalles sobre la definición de parámetros en Swagger, consulta la documentación oficial de OpenAPI.
Jorge García
Fullstack developer