Cómo anotar un parámetro de tipo form-urlencoded de una lista Java para Swagger?
Tengo este punto final de la API que espera un parámetro de matriz form-urlencoded. Este es el fragmento de código relevante en Java:
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces(MediaType.APPLICATION_JSON)
public Response addItems(@Parameter(description = "Items to add") @FormParam("items") List<long> items) {
return service.addItems(items);
}
No puedo acceder al punto final desde el Swagger UI generado debido al siguiente error:
RESTEASY003870: No se puede extraer el parámetro de la solicitud HTTP: el valor javax.ws.rs.FormParam("items") es '1%2C2%2C3'
Según lo que he leído, Swagger está haciendo esta solicitud:
curl -X 'POST' \
'http://localhost:8080/items' \
-H 'accept: */*' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'items=1,2,3'
Me parece que el culpable es cómo Swagger serializa la matriz: Swagger envía esto items=1,2,3
mientras que RESTEasy espera esto items=1&items=2&items=3
.
Ya he leído la documentación relevante de Swagger e intentado todas las combinaciones de estilo/explode, incluyendo aquellas que parecen tener más sentido para mí (style = ParameterStyle.SIMPLE
, explode = TRUE
, que por cierto debería ser el comportamiento predeterminado), sin suerte.
Entonces, ¿cómo debo anotar este punto final para que Swagger pueda invocarlo?
davy.ai
Para anotar correctamente este punto final de manera que Swagger pueda enviar la solicitud con el formato esperado
items=1&items=2&items=3
, necesitas usar la anotación@ApiImplicitParams
con las anotaciones@ApiImplicitParam
para cada parámetro.Así es como puedes modificar el código:
Explicación:
@ApiImplicitParams
se utiliza para enumerar todos los parámetros implícitos de una operación.@ApiImplicitParam
se utiliza para cada parámetro. Aquí están las anotaciones importantes utilizadas:name
: el nombre del parámetro (en este caso, “items”)paramType
: la ubicación del parámetro (en este caso, “query”)dataType
: el tipo de dato del parámetro (en este caso, “array”)collectionFormat
: el formato del array (en este caso, “multi” para separar los valores con “&”)required
: si el parámetro es requerido (en este caso, “true”)value
: la descripción del parámetro (en este caso, “Items to add”)example
: un valor de ejemplo para el parámetro (en este caso, “1,2,3”)Con estas anotaciones, Swagger debería poder invocar correctamente el punto final.