SpringDoc OpenAPI 中多文件编码注解的正确使用方式

在基于Spring Boot的REST API开发中，SpringDoc OpenAPI是一个非常流行的库，它能够自动生成OpenAPI 3.0规范的文档。当处理文件上传特别是多部分表单数据时，开发者经常需要为不同的表单字段指定不同的内容类型编码。

问题背景

在SpringDoc OpenAPI的早期版本中，开发者可能会遇到一个问题：当尝试为不同的表单字段分别指定内容类型编码时，只有第一个编码注解会被识别。例如，在一个文件上传接口中，开发者可能希望：

1. 文件字段使用application/octet-stream类型
2. 附加的JSON数据字段使用application/json类型

错误的使用方式

开发者可能会尝试为每个@RequestPart参数单独添加@RequestBody注解，如下所示：

@PostMapping(value ="/first", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadMultipartWithBody(
    @RequestBody(content = @Content(encoding = @Encoding(name = "file", contentType = MediaType.APPLICATION_OCTET_STREAM_VALUE)))
    @Parameter(required = true)
    @RequestPart("file") MultipartFile file,
    @RequestBody(content = @Content(encoding = @Encoding(name = "dto", contentType = MediaType.APPLICATION_JSON_VALUE)))
    @Parameter(description = "An extra JSON payload sent with file")
    @RequestPart("dto")
    DTO dto) {
    return ResponseEntity.ok("Request Accepted: " + dto.toString());
}

这种方式会导致只有第一个编码定义被SpringDoc OpenAPI识别。

正确的解决方案

正确的做法是将所有编码定义统一放在方法级别的@RequestBody注解中，使用数组形式指定多个@Encoding：

@PostMapping(value ="/first", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@RequestBody(content = @Content(encoding = {
    @Encoding(name = "file", contentType = MediaType.APPLICATION_OCTET_STREAM_VALUE),
    @Encoding(name = "dto", contentType = MediaType.APPLICATION_JSON_VALUE)
}))
public ResponseEntity<String> uploadMultipartWithBody(
    @Parameter(required = true)
    @RequestPart("file") MultipartFile file,
    @Parameter(description = "An extra JSON payload sent with file")
    @RequestPart("dto")
    DTO dto) {
    return ResponseEntity.ok("Request Accepted: " + dto.toString());
}

生成的OpenAPI文档效果

采用上述正确方式后，生成的OpenAPI文档将包含完整的编码定义：

requestBody:
  content:
    'multipart/form-data':
      schema:
        type: object
        required:
          - dto
          - file
        properties:
          dto:
            type: string
          file:
            type: string
            format: binary
      encoding:
        file:
          contentType: application/octet-stream
        dto:
          contentType: application/json

技术要点总结

1. 对于多部分表单数据的编码定义，应该使用方法级别的@RequestBody注解
2. 多个编码定义需要使用@Encoding数组形式指定
3. 每个编码定义需要指定字段名称(name)和对应的内容类型(contentType)
4. 参数级别的@Parameter注解仍然可以用于指定参数的描述和是否必需等属性

这种设计符合OpenAPI规范的要求，确保了API文档能够准确描述多部分请求中不同字段的内容类型编码方式。