Swagger Codegen生成多部分上传接口时，如何指定必填字段？

问题背景 #

我使用Java 11，基于OpenAPI 3实现包含文件和其他字段的多部分表单数据上传请求，相关定义和配置如下：

OpenAPI YAML定义 #

/myobjects/:
  post:
    tags:
      - my-objects
    summary: Adding my object
    operationId: addmyobject
    description: Creates a new my object.
    requestBody:
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/MyObjectDTO'
      required: true
...
MyObjectDTO:
  type: object
  properties:
    myId:
      type: integer
      format: int
      readOnly: true
    name:
      type: string
      maxLength: 100
      required: true
      example: myRequest
...
    myFile:
      type: string
      format: binary
  required:
    - name

Swagger Codegen Maven插件配置 #

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.17</version>
    ...
    <configuration>
        ...
        <generateApis>true</generateApis>
        <generateApiTests>false</generateApiTests>
        <generateModelTests>false</generateModelTests>
        <generateApiDocumentation>true</generateApiDocumentation>
        <generateModels>true</generateModels>
        <generateSupportingFiles>false</generateSupportingFiles>
        <languageSpecificPrimitives>true</languageSpecificPrimitives>
        <importMappings>
            ...
        </importMappings>
        <configOptions>
            <interfaceOnly>true</interfaceOnly>
            <java8>false</java8>
            <dateLibrary>java8</dateLibrary>
            <sourceFolder>.</sourceFolder>
            <throwsException>true</throwsException>
            <useTags>true</useTags>
        </configOptions>
    </configuration>
</plugin>

问题现象 #

生成的API接口中，DTO的所有字段（包括myId）都被标记为必填，但我仅在DTO中指定了name为必填字段：

@Operation(summary = "Adding my object", description = "Creates a new my object.", tags={ "my-objects" })
@ApiResponses(value = { 
    @ApiResponse(responseCode = "201", description = "OK", content = @Content(schema = @Schema(implementation = ResponseData.class))) })
@RequestMapping(value = "/myobjects/",
    produces = { "application/json" }, 
    consumes = { "multipart/form-data" },
    method = RequestMethod.POST)
default ResponseEntity<ResponseData> addmyobject(
@Parameter(description = "", required=true) @RequestParam(value="myId", required=true) Integer myId
,
@Parameter(description = "", required=true) @RequestParam(value="name", required=true) String name
,
...
,
@Parameter(description = "file detail") @Valid @RequestPart("file") MultipartFile myFile
) throws Exception {

解决方法 #

1. 修正OpenAPI YAML定义 #

• 移除冗余的字段级required声明：name字段中的required: true可以删除，因为已经在DTO根级的required数组中声明，避免重复定义导致识别异常。
• 排除只读字段：myId标记了readOnly: true，属于后端生成字段，不应出现在POST请求参数中。如果引用DTO仍无法排除，建议直接在请求体中定义schema，替代DTO引用：

  requestBody:
    content:
      multipart/form-data:
        schema:
          type: object
          properties:
            name:
              type: string
              maxLength: 100
              example: myRequest
            myFile:
              type: string
              format: binary
          required:
            - name
    required: true
  

  这种方式更精准，只保留请求需要的字段。

2. 调整Swagger Codegen插件配置 #

• 启用Bean Validation支持：在configOptions中添加useBeanValidation: true，让生成器尊重DTO的必填规则：

  <configOptions>
      <interfaceOnly>true</interfaceOnly>
      <java8>false</java8>
      <dateLibrary>java8</dateLibrary>
      <sourceFolder>.</sourceFolder>
      <throwsException>true</throwsException>
      <useTags>true</useTags>
      <useBeanValidation>true</useBeanValidation>
  </configOptions>
  

• 升级插件版本：3.0.17版本存在multipart字段识别bug，建议升级到3.0.34及以上稳定版本，提升OpenAPI 3兼容性。
• 强制忽略只读字段：如果仍有只读字段被生成到接口中，添加ignoreReadOnly: true配置：

  <configOptions>
      <!-- 其他配置 -->
      <ignoreReadOnly>true</ignoreReadOnly>
  </configOptions>
  

3. 自定义字段必填性 #

如果需要将myFile设为必填，只需在YAML的required数组中添加myFile，生成的代码会自动标记@RequestPart(required=true)。

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