我直接给你上适配io.swagger.core.v3 2.1.3版本的完整代码示例，然后拆解每个注解的作用，这样你能快速对应到自己的业务场景：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Encoding;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
public class MultipartUploadController {

    @Operation(
        summary = "上传带选项与备注的附件",
        description = "接收multipart-form-data类型请求，包含两个必填字段和一个可选文本字段",
        // 重点：在这里配置multipart请求体的详细信息
        requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
            content = @Content(
                mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
                schema = @Schema(type = "object"),
                // 给每个字段指定内容类型，适配不同的输入类型
                encoding = {
                    @Encoding(
                        name = "my-attachment",
                        contentType = "application/octet-stream" // 可以换成具体类型如image/png，根据业务调整
                    ),
                    @Encoding(
                        name = "options",
                        contentType = "*/*" // 兼容文件和文本，所以用通配符
                    )
                }
            )
        ),
        responses = {
            @ApiResponse(responseCode = "200", description = "上传成功")
        }
    )
    @PostMapping(
        path = "/api/upload",
        consumes = MediaType.MULTIPART_FORM_DATA_VALUE
    )
    public String processUpload(
        // 必填的附件字段
        @RequestPart("my-attachment")
        @Parameter(description = "必填的附件文件", required = true)
        MultipartFile myAttachment,

        // 必填的多类型选项字段
        @RequestPart("options")
        @Parameter(description = "必填选项，支持文件或文本内容", required = true)
        Object options, // 用Object兼容MultipartFile和String，实际业务里可以做类型判断

        // 可选的备注字段
        @RequestPart(value = "note", required = false)
        @Parameter(description = "可选的备注文本")
        String note
    ) {
        // 这里写你的业务逻辑
        return "Upload completed successfully";
    }
}

关键注解拆解，帮你理清逻辑 #

1. @Operation里怎么描述multipart？ #

你之前找@Operation的用法没错，只是需要通过它的requestBody属性来配置：

• 用@Content指定mediaType为multipart/form-data，明确请求体类型
• encoding数组是核心：给每个字段指定对应的内容类型，比如my-attachment是文件就设为二进制流类型，options支持多种类型就用*/*通配符，这样Swagger UI会正确渲染对应的输入控件。

2. 字段的必填性与类型绑定 #

• 每个multipart字段用@RequestPart绑定（别用@RequestParam，前者更适合multipart场景）
• 配合@Parameter注解标记必填性和描述，比如required = true就对应你要求的必填字段
• options字段用Object类型是为了兼容文件（MultipartFile）和文本（String），实际业务中你可以在方法内做类型判断处理。

3. 版本适配注意点 #

你用的是2.1.3版本，所有上述注解都是这个版本支持的，注意别导错包：

• 要导入io.swagger.v3.oas.annotations下的注解，别和Spring自带的@RequestBody搞混。

最终效果 #

在Swagger UI里，这个接口会显示：

• 一个必填的文件上传框对应my-attachment
• 一个可切换的输入区域（文件/文本）对应options
• 一个可选的文本输入框对应note

完全符合你要求的字段定义~

内容的提问来源于stack exchange，提问作者diziaq