OpenAPI 3.0.1下载Zip文件API配置问题求助

你的OpenAPI 3.0.1定义存在几个关键问题，导致下载的文件无法被识别为Zip格式：

• 参数number的示例错误：该参数用于传递预订号码，但你填写的示例是attachment; filename="name.zip"，完全不符合参数用途，属于错误配置。
• Content-Disposition头的schema格式错误：该响应头本质是字符串类型，不需要添加format: binary声明，这个多余配置会造成解析混淆。
• 响应内容类型与schema不匹配：针对Zip文件，更精准的Content-Type是application/zip而非application/octet-stream；同时schema缺少format: binary，无法正确标识二进制文件内容。

以下是修正后的OpenAPI定义：

/download:
  get:
    parameters:
      - name: number
        in: query
        description: The Booking Number which you want to download Files
        required: true
        style: form
        explode: true
        schema:
          type: string
        example: "BOOKING-001"  # 替换为真实的预订号码示例
    responses:
      '200':
        description: OK
        headers:
          Content-Disposition:
            style: simple
            explode: false
            schema:
              type: string
              example: 'attachment; filename="name.zip"'
        content:
          application/zip:
            schema:
              type: string
              format: binary
              description: Zip file containing the requested booking files

同时需要确保后端服务返回响应时：

1. 严格设置Content-Type为application/zip
2. Content-Disposition头正确携带文件名（后缀必须为.zip）
3. 响应体是真实的二进制Zip文件内容，而非字符串或其他格式数据

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