swagger-codegen-maven-plugin使用@RequestParam而不是@RequestPart生成多部分表单数据请求api

Question

我使用请求对象FileMetadata上传文件元数据信息，并将其作为文件上传多部分表单数据请求的一部分发送。但是swagger-codegen-maven-plugin生成的代码以@RequestParam作为表单数据请求的第一部分。由于这个原因，我必须在WebMvcConfigurer中注册一个'JSON‘转换器，以便将请求部分转换为FileMetadata，否则将通过以下错误：

o.s.w.s.m.s.DefaultHandlerExceptionResolver:208 - Resolved [org.springframework.web.method.annotation.MethodArgumentConversionNotSupportedException: Failed to convert value of type 'java.lang.String' to required type 'com.upload.file.generated.model.FileMetadata'; nested exception is java.lang.IllegalStateException: Cannot convert value of type 'java.lang.String' to required type 'com.upload.file.generated.model.FileMetadata': no matching editors or conversion strategy found]

我有以下问题：

1. 是否有任何选项可以生成两个带有@RequestPart注释的请求参数？
2. 如何为FileMetadata请求param生成@Valid注释？

配置详细信息如下：

开放API规范：

openapi: 3.0.3
...
...
paths:
  /api/v1/upload:
    post:
      tags:
      - File upload
      summary: Upload a file
      operationId: uploadFile
      requestBody:
        description: File that needs to be uploaded
        required: true
        content:
          multipart/form-data: # Media type 
            schema:
              required:
              - metadata
              - file
              type: object
              properties:
                metadata:
                  $ref: '#/components/schemas/FileMetadata'
                file:
                  type: string
                  format: binary
            encoding:
              metadata: 
                contentType: application/json
              file: 
                contentType: application/octet-stream
      responses:
        201:
          description: OK
        400:
          description: Invalid input
        401:
          description: Unauthorized
        403:
          description: Forbidden       
        404:
          description: Not Found

生成的API代码：

        @Operation(summary = "Upload a file", description = "", tags={ "File upload" })
    @ApiResponses(value = {... })
    @RequestMapping(value = "/api/v1/upload",
        produces = { "application/json" }, 
        consumes = { "multipart/form-data" }, 
        method = RequestMethod.POST)
    ResponseEntity<Void> uploadFile(@Parameter(in = ParameterIn.DEFAULT, description = "", required=true,schema=@Schema()) @RequestParam(value="metadata", required=true)  FileMetadata metadata, @Parameter(description = "file detail") @Valid @RequestPart("file") MultipartFile file);

Pom.xml：

                <plugin>
                <groupId>io.swagger.codegen.v3</groupId>
                <artifactId>swagger-codegen-maven-plugin</artifactId>
                <version>3.0.33</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/openapi.yaml</inputSpec>
                            <language>spring</language>                         
                            <output>${project.basedir}</output>
                            <modelPackage>com.file.upload.generated.model</modelPackage>
                            <apiPackage>com.file.upload.generated.api</apiPackage>
                            <generateModels>true</generateModels>
                            <generateModelDocumentation>false</generateModelDocumentation>
                            <generateApis>true</generateApis>
                            <generateApiDocumentation>false</generateApiDocumentation>
                            <generateApiTests>false</generateApiTests>
                            <generateSupportingFiles>false</generateSupportingFiles>
                            <configOptions>
                                <performBeanValidation>true</performBeanValidation>
                                <useBeanValidation>true</useBeanValidation>
                                <hideGenerationTimestamp>true</hideGenerationTimestamp>
                                <dateLibrary>java11-localdatetime</dateLibrary>
                            </configOptions>
                            <importMappings>
                                <importMapping>Date=java.time.LocalDate</importMapping>                             
                            </importMappings>
                            <typeMappings>
                                <typeMapping>Date=LocalDate</typeMapping>
                            </typeMappings>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Answer 1

实现这两个目标的最干净的方法是在项目中提供定制的胡子模板。您可以在Swagger生成器库 ->中找到它们，或者更准确地说，您可以在生成器的版本3.0.33的文件夹中找到Spring模板。

对于您的情况，相应的模板将是formParams.mustache，在这里，我建议从以下位置修改行：

[...] defaultValue="{{{defaultValue}}}"{{/defaultValue}})){{/useOas2}} @RequestParam(value="{{baseName}}"{{#required}}, required=true [...]

至：

defaultValue="{{{defaultValue}}}"{{/defaultValue}})){{/useOas2}}{{#useBeanValidation}} @Valid{{/useBeanValidation}} @RequestPart(value="{{baseName}}"{{#required}}, required=true{{/required}}[...]

要使用这些自定义模板，只需将模板目录添加到插件配置中：

<configuration>
     [...]
     <templateDirectory>src/main/resources/mustache/handlebars/JavaSpring</templateDirectory>
     [...]
</configuration>

关于使用胡子模板的更广泛的指南，我可以从关于这个主题的openapi生成器中推荐指南。