在 Spring 中使用多部分请求自动生成 OpenAPI

Question

I have a problem with the OpenAPI generator in a spring boot application generating the definition of a REST endpoint that accepts a multipart request.

When I am explicitly defining the parts like shown below. It generates an OpenAPI definition that is working/valid when used in for example in Azure API Management.

@PostMapping(consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public List<String> upload(@RequestPart MultipartFile file, @RequestPart UploadMetaData data) {

  . . .

}

paths:
  /api/v1/upload:
    post:
      operationId: upload
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - data
              - file
              type: object
              properties:
                gatewayId:
                  type: string
                file:
                  type: string
                  format: binary
                data:
                  $ref: '#/components/schemas/UploadMetaData'
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  type: string

But when I am trying to use MultipartRequest instead of the annotated - File , the controller itself is still working as expected accepting an arbitrary list of multipart segments when I call it directly, but the OpenAPI definition that is generated is not reflecting the actual interface because it is trying to use the request parameter as an URL path parameter, so when I import this spec into Azure API Management it is not working.

@PostMapping(consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public List<String> upload(MultipartRequest request) {

  . . .

}

paths:
  /api/v1/upload:
  post:
    operationId: upload
    parameters:
    - name: request
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/MultipartRequest'
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: string
    responses:
      "200":
        description: OK
        content:
          '*/*':
            schema:
              type: array
              items:
                type: string

Other than giving my API a name, I didn't configure anything special for the generator:

@OpenAPIDefinition(info = @Info(title = "My REST API", version = "1.0"))
public class MySpringApplication {

. . . 

}

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.5.12</version>
</dependency>

Is this a bug or am I missing some annotation or other configuration here?

Answer 1

The MultipartRequest , is not supported out of the box. You can use the following code to enable the support.

static{
    SpringDocUtils.getConfig().addFileType(MultipartRequest.class);
}

This support will be added for the future release.