如何在OpenAPI的multipart/form-data中指定图片类型枚举？

你的问题出在把媒体类型枚举直接绑定到了binary格式的字段上，openapi-generator会把这些枚举值解析成文件内容的可选值，而非允许的文件媒体类型，所以生成客户端时会变成二进制值。下面是两种正确的写法：

方案一：使用OpenAPI标准contentMediaType约束媒体类型（推荐） #

这个关键字是OpenAPI 3.0+的标准用法，直接在文件字段的schema里指定允许的媒体类型枚举，规范更清晰，兼容性也更好：

/players:
  post:
    operationId: createPlayer
    summary: 创建新玩家
    description: 创建一个新玩家。
    tags:
      - Players
    requestBody:
      description: 可选参数。
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - id
            properties:
              address:
                type: object
                properties:
                  address_line:
                    type: string
        multipart/form-data:
          schema:
            type: object
            required:
              - tag_picture
            properties:
              tag_picture:
                type: string
                format: binary
                example: label.jpg
                contentMediaType:
                  enum:
                    - image/png
                    - image/jpeg

方案二：通过encoding字段指定允许的媒体类型 #

在multipart/form-data的content配置下，添加encoding节点，针对tag_picture字段明确允许的Content-Type：

/players:
  post:
    operationId: createPlayer
    summary: 创建新玩家
    description: 创建一个新玩家。
    tags:
      - Players
    requestBody:
      description: 可选参数。
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - id
            properties:
              address:
                type: object
                properties:
                  address_line:
                    type: string
        multipart/form-data:
          schema:
            type: object
            required:
              - tag_picture
            properties:
              tag_picture:
                type: string
                format: binary
                example: label.jpg
          encoding:
            tag_picture:
              # 用逗号分隔的字符串指定允许的媒体类型
              contentType: "image/png, image/jpeg"
              # 部分openapi-generator版本支持数组形式：
              # allowedContentTypes:
              #   - image/png
              #   - image/jpeg

注意事项 #

• 不同版本的openapi-generator对关键字的支持略有差异，优先用方案一的contentMediaType，它是OpenAPI标准定义，适配性更强。
• 两种写法都能让生成的客户端代码正确识别文件类型约束，不会把枚举值转成二进制。

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