Swagger UI unterstützt nicht das korrekte Hochladen einer Datei für RestEasy

Question

Ich benutze ein JAX-RS (RestEasy) zusammen mit einem Swagger. Einer meiner Endpunkte kann eine Datei hochladen. Definierter Weg um die Datei hochzuladen (in RestEasy), ist eine org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput als Parameter anzugeben.

Hier ist mein Endpunkt:

@PUT 
@Path("/apis/{id}/file") 
@Consumes(MediaType.MULTIPART_FORM_DATA) 
@Produces(MediaType.APPLICATION_JSON) 
@ApiOperation(value = "Registers a file.", code = 201, nickname = "registerFile") 
@ApiResponses(
    value = { 
     @ApiResponse(code = 201, message = "File created.", 
        response = FileCreated.class), 
     @ApiResponse(code = 400, message = "Invalid parameters."), 
     @ApiResponse(code = 404, message = "API is not found.")}) 
Response registerFile(
    @ApiParam(value = "API ID.", required = true) @PathParam("id") String apiId, 
    @ApiParam(value = "File to register.", required = true, type = "file", name = "apiFile") 
     MultipartFormDataInput apiFile) throws AppException; 

Was ist das Problem?

Leider generiert swagger-ui ein Schema basierend auf den inneren Eigenschaften des MultipartFormDataInput anstelle einer Schaltfläche zum Hochladen der Datei. Ich habe versucht, eine @FormParam Annotation (um anzuzeigen, dass der Bereitstellungsparameter als Datei interpretiert werden soll) zusammen mit dem MultipartFormDataInput Parameter, aber dann möchte die App nicht kompilieren.

Frage: Gibt es eine Lösung/Workaround, um die Schaltfläche zum Hochladen der Datei im Swagger-Ui bereitzustellen?

Answer 1

Die Lösung @ApiParam von Ihrem apiFile Argumente Entfernen und Hinzufügen von @ApiImplicitParam (die nicht an Jax-RS gebunden ist und ermöglicht Parameter manuell definieren) über der Methode:

@ApiImplicitParams({@ApiImplicitParam (value = "File to register.", required = true, dataType = "file", name = "apiFile", paramType="formData")}) 

Answer 2

Die Endlösung

The Die endgültige Lösung enthält eine ausgewählte Antwort, aber anstatt @ApiParam zu entfernen, sollten wir @ApiParam(hidden = true) hinzufügen. Warum?

Wenn wir @ApiParam zu entfernen, gibt es zwei Felder: apiId, body mit den inneren Eigenschaften der MultipartFormDataInput und die Taste, um die Datei in dem Prahlerei-ui hochladen. Dieses Feld body ist ein Nebeneffekt. Um dieses Problem zu beheben, sollten wir @ApiParam(hidden = true) bereitstellen, dann gibt es das Feld mit apiId und die Schaltfläche zum Hochladen der Datei im Swagger-Ui.

BTW: Ich testete unten Code für swagger-ui in 1.5.12 Version.

@PUT 
@Path("/apis/{id}/file") 
@Consumes(MediaType.MULTIPART_FORM_DATA) 
@Produces(MediaType.APPLICATION_JSON) 
@ApiOperation(value = "Registers a file.", code = 201, nickname = "registerFile") 
@ApiResponses(
    value = { 
     @ApiResponse(code = 201, message = "File created.", 
        response = FileCreated.class), 
     @ApiResponse(code = 400, message = "Invalid parameters."), 
     @ApiResponse(code = 404, message = "API is not found.")}) 
@ApiImplicitParams(
    @ApiImplicitParam(value = "File to register.", required = true, dataType = "file", 
         name = "apiFile", paramType = "formData")) 
Response registerFile(
    @ApiParam(value = "API ID.", required = true) @PathParam("id") String apiId, 
    @ApiParam(hidden = true) MultipartFormDataInput apiFile) throws AppException;