如何定义图片上传与获取的OpenAPI描述？类型与格式选型疑问

问题分析 #

你当前用application/json传递图片并将image字段设为string+byte的写法，本质是通过base64编码传递图片，但这并非文件上传的常规做法——大图片用base64会增加约33%的体积，且性能不如直接传二进制文件。下面给出两种符合规范的实现方案：

方案1：用multipart/form-data上传（推荐） #

这是上传文件的标准方式，支持直接传递二进制图片，无需编码，适合绝大多数场景：

/uploadimage:
  post:
    tags: 
      - images
    summary: 上传图片
    requestBody:  
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              imageID:
                type: integer
                example: 103983
              image:
                type: string
                format: binary  # 表示二进制文件
                description: 要上传的图片文件
      required:
        - image  # 必填字段可根据实际需求调整

方案2：用application/json传递base64编码图片（适合小图） #

如果必须通过JSON传递，format: byte是OpenAPI规范中表示base64编码二进制数据的正确写法，此时image字段的值是图片文件的base64编码字符串：

/uploadimage:
  post:
    tags: 
      - images
    summary: 上传base64编码的图片
    requestBody:  
      content:
        application/json:
          schema:
            type: object
            properties:
              imageID:
                type: integer
                example: 103983
              image:
                type: string
                format: byte  # 对应base64编码的二进制数据
                example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      required:
        - image

图片获取API示例 #

补充对应的图片获取接口，通常返回二进制图片数据：

/getimage/{imageID}:
  get:
    tags:
      - images
    summary: 根据ID获取图片
    parameters:
      - name: imageID
        in: path
        required: true
        schema:
          type: integer
          example: 103983
    responses:
      '200':
        description: 成功返回图片
        content:
          image/png:  # 支持的图片格式，可按需添加image/jpeg等
            schema:
              type: string
              format: binary

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