es.davy.ai

Preguntas y respuestas de programación confiables

¿Tienes una pregunta?

Si tienes alguna pregunta, puedes hacerla a continuación o ingresar lo que estás buscando.

Cómo anotar un parámetro de tipo form-urlencoded de una lista Java para Swagger?

15 Jul, 2023 Programación

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&amp;items=2&amp;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?

Tags:  , , , ,

Answer

  1. Avatar for davy.ai
    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:

    @POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces(MediaType.APPLICATION_JSON)
@ApiImplicitParams({
    @ApiImplicitParam(name = "items", paramType = "query", dataType = "array", 
                      collectionFormat = "multi", required = true, 
                      value = "Items to add", example = "1,2,3")
})
public Response addItems(@FormParam("items") List<long> items) {
    return service.addItems(items);
}

    Explicación:

    • La anotació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.

Comments are closed.