How Springdoc and OpenApi write multipart/form-data and file upload interfaces

First go to the swagger official document:

https://swagger.io/specification/#schema

The springdoc version I am currently using is 1.69
. Reference content:

Special Considerations for multipart Content

It is common to use multipart/form-data as a Content-Type when transferring request bodies to operations. In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content. This supports complex structures as well as supporting mechanisms for multiple file uploads.

When passing in multipart types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default Content-Types are defined for multipart:

If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain

If the property is complex, or an array of complex values, the default Content-Type is application/json

If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream

The translation is:

Special considerations for multipart content

It is common to use multipart/form-data as the Content-Type when transferring the request body to an action. Unlike 2.0, when using multipart content, the mode is REQUIRED to define the input parameters of the operation. This supports complex structures as well as mechanisms to support multiple file uploads.

When passing a multipart type, boundaries can be used to separate the parts of the content being passed—thus, the following default content types are defined for multipart:

If the property is a primitive or an array of primitive values, the default Content-Type is text/plain

If the property is complex, or an array of complex values, the default Content-Type is application/json

If the attribute is type: string, format: binary or format: base64 (aka file object), then the default Content-Type is application/octet-stream

Example Examples:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {
    
    }
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'

According to the above instructions, write the springdoc related interface code in springboot:
(You can change CommonResult to String)

@Operation(summary = "上传文件")
@PostMapping("/files/upload")
@RequestBody(content = {
    
    @Content(
    mediaType = "multipart/form-data",
    schema = @Schema(type = "object"),
    schemaProperties = {
    
    
        @SchemaProperty(
            name = "multipartFile",
            schema = @Schema(type = "string",format = "binary")
        ),
        @SchemaProperty(
            name = "info",
            schema = @Schema(type = "object")
        )}
)})
public CommonResult<String> upload(MultipartFile multipartFile,
                     String info){
    
    
    return CommonResult.success(multipartFile.toString() + info);
}

http://localhost:8888/v3/api-docs中:

{
    
    
  "/files/upload": {
    
    
    "post": {
    
    
      "tags": [
        "文件管理"
      ],
      "summary": "上传文件",
      "operationId": "upload",
      "requestBody": {
    
    
        "content": {
    
    
          "application/form-data": {
    
    
            "schema": {
    
    
              "type": "object",
              "properties": {
    
    
                "file": {
    
    
                  "type": "string",
                  "format": "binary"
                },
                "info": {
    
    
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "responses": {
    
    
        "200": {
    
    
          "description": "OK",
          "content": {
    
    
            "*/*": {
    
    
              "schema": {
    
    
                "$ref": "#/components/schemas/CommonResultString"
              }
            }
          }
        }
      }
    }
  }
}

In swagger-ui: Please add a picture description

Request and response sent:
Please add a picture description

success!

Summary: Official documents have to be read carefully