如何使用 Quarkus 在 RestEasy 中为 MultipartFormDataInput 提供 swagger 注释

Posted 2023-02-16

【中文标题】如何使用 Quarkus 在 RestEasy 中为 MultipartFormDataInput 提供 swagger 注释

【英文标题】：How to provide swagger annotation for MultipartFormDataInput in RestEasy with Quarkus

【发布时间】：2021-01-12 17:13:48

【问题描述】：

在使用 RestEasy 框架开发 Quarkus 时，我可以使用 MultipartFormDataInput 上传文件。此功能按预期工作，但我无法为 swagger UI 提供正确的开放 API 注释。我尝试了多种选择和组合，但没有结果。请帮我。我在下面提供了示例代码。

@Operation(summary = "Upload a single file", description = "Upload a single file")
    @APIResponses(
            @APIResponse(responseCode = "200", description = "Upload file successfully"),
            @APIResponse(name = "500", responseCode = "500", description = "Internal service error") )
    @RequestBody(content = @Content(
            mediaType = MediaType.MULTIPART_FORM_DATA,
            schema = @Schema(type = SchemaType.STRING, format = "binary"),
            encoding = @Encoding(name = "attachment", contentType = "application/octet-stream")))
    @POST
    @Path("/singleFile")
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces(MediaType.TEXT_PLAIN)
    public Response handleFileUpload(@MultipartForm MultipartFormDataInput input) 
        String fileName = null;

        Map<String, List<InputPart>> uploadForm = input.getFormDataMap();
        // Get file data to save
        List<InputPart> inputParts = uploadForm.get("attachment");
        for (InputPart inputPart : inputParts) 
            try 
                MultivaluedMap<String, String> header = inputPart.getHeaders();
                fileName = getFileName(header);
                InputStream inputStream = inputPart.getBody(InputStream.class, null);
                byte[] bytes = IOUtils.toByteArray(inputStream);
                File customDir = new File(UPLOAD_DIR);
                if (!customDir.exists()) 
                    customDir.mkdir();
                
                fileName = customDir.getCanonicalPath() + File.separator + fileName;
                Files.write(Paths.get(fileName), bytes, StandardOpenOption.CREATE);
                return Response.status(200).entity("Uploaded file name : " + fileName).build();
             catch (Exception e) 
                e.printStackTrace();
            
        
        return Response.status(200).entity("Uploaded file name : " + fileName).build();
    

我也参考了以下链接。

https://community.smartbear.com/t5/Swagger-Open-Source-Tools/How-to-swagger-annotate-multipart-form-data-with-resteasy/td-p/178776

https://github.com/swagger-api/swagger-core/issues/3050

如果我使用@Schema(type = SchemaType.STRING, format = "binary") and @PartType(MediaType.APPLICATION_OCTET_STREAM) 注释创建一个名为MultipartBody 的单独类，我能够生成招摇的用户界面。但我的要求是只使用MultipartFormDataInput。

【问题讨论】：

你认为这个问题有帮助吗？ ***.com/questions/44950791/…

我已经试过了，但是对最新版本还是不行。

很遗憾听到@Sambit

【参考方案1】：

你快到了 :) 只需在 RequestBody/Schema 中使用一个专用类并告诉 OpenAPI 忽略你的方法的参数。

@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@RequestBody(content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA,
    schema = @Schema(implementation = MultipartBody.class))
)
@Operation(operationId = "uploadFile")
public Response uploadFile(@Parameter(hidden = true) MultipartFormDataInput input) 
//... your logic here

需要注意两点：@Parameter(hidden = true) 告诉 Smallrye OpenAPI 在生成 Schema 模型时不要考虑您的 MultipartFormDataInput。然后，您需要使用@RequestBody 明确地告诉描述模式，其中MultipartBody 是一个描述所有输入参数的类（如果您想例如传递其他道具以及文件有效负载，您可以在那里添加更多参数）

public class MultipartBody 

    @FormParam("file")
    @Schema(type = SchemaType.STRING, format = "binary", description = "file data")
    public String file;


    @FormParam("fileName")
    @PartType(MediaType.TEXT_PLAIN)
    public String fileName;

只需确保MultipartBody 中的@FormParam 注释字段与您希望在MultipartFormDataInput 中找到的“,,parts”相匹配 - 例如，在您的情况下，文件属性应具有@FormParam("attachment")