前言

swagger 升级V3后发现swagger ui 对附件类型参数无法支持，
springfox迁移springdoc后附件类型参数无法支持

预期结果：
在这里插入图片描述

一、swagger v3 附件类型参数

多参数，对附件采用@RequestPart可以解决问题。

    @ApiOperation(value = "上传文件")
    @ApiOperationSupport(order = 2)
    @PostMapping(value = "/v1/upload")
    public Result<AttachmentResp> upload(@RequestPart("file") @ApiParam(name = "file", value = "上传文件", required = true) MultipartFile file,
                                         @RequestParam(value = "path") @ApiParam(name = "path", value = "eg:data/plan/", required = true) String path,
                                         @RequestParam(value = "clientId") @ApiParam(name = "clientId", value = "应用id", required = true) String clientId) {
        AttachmentResp upload = service.upload(file, path, clientId);
        return Result.success(upload);
    }

封装入参为对象实现方式
@ApiModelProperty(value = "上传文件", required = true, dataType = "__file")
对文件类型参数特别指定文件类型

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class FileReq {
    @ApiModelProperty(value = "上传文件", required = true, dataType = "__file")
    private MultipartFile file;
    @ApiModelProperty(name = "path", value = "eg:data/plan/", required = true)
    private String path;
    @ApiModelProperty(name = "md5")
    private String fileIdentifier;
    @ApiModelProperty(name = "clientId", value = "应用id", required = true)
    private String clientId;
}

二、springdoc 附件类型参数

1.springfox迁移springdoc注解对应关系

用 swagger 3 注释替换 swagger 2 注释（它已经包含在springdoc-openapi-ui依赖项中）。swagger 3 注释的包是io.swagger.v3.oas.annotations.

@Api→@Tag
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
@ApiImplicitParam→@Parameter
@ApiImplicitParams→@Parameters
@ApiModel→@Schema
@ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)
@ApiModelProperty→@Schema
@ApiOperation(value = “foo”, notes = “bar”)→@Operation(summary = “foo”, description = “bar”)
@ApiParam→@Parameter
@ApiResponse(code = 404, message = “foo”)→@ApiResponse(responseCode = “404”, description = “foo”)

https://springdoc.org/#migrating-from-springfox

2.springdoc 附件参数处理

各种尝试后无法封装参数，只能采用多参数形式，其中附件采用@RequestPart 其他参数采用@RequestParam

    @PostMapping(value = "/v1/upload")
    public Result<AttachmentResp> upload(@RequestParam @Parameter(description = "上传路径", required = true) String path,
                                         @Parameter(description = "文件MD5") String fileIdentifier,
                                         @RequestParam @Parameter(description = "应用id", required = true) String clientId,
                                         @RequestPart @Parameter(description = "上传文件", required = true) MultipartFile file) {
        FileReq req = FileReq.builder().file(file).path(path).fileIdentifier(fileIdentifier).clientId(clientId).build();
        AttachmentResp upload = service.upload(req);
        return Result.success(upload);
    }