OpenAPI 2.0定义Zip返回类型：如何让TypeScript生成Observable<Uint8Array>

问题场景 #

现有OpenAPI YAML配置：

/document/zip:
get:
  produces:
    - application/zip
  tags:
    - zipFileFolder
  operationId: getRawDocumentFileZipData
  parameters:
    - in: body
      name: args
      required: true
      schema:
        type: array
        items:
          $ref: './definitions/model/document-metadata.yaml#/DocumentMetadata'
  responses:
    200:
      description: The document file data as a zip file
      schema:
        type: string
        format: binary
    400:
      description: bad input parameter

输入类型定义：

DocumentMetadata:
  type: object
  required:
    - id
    - name
  properties:
    id:
      type: number
    fileName:
      type: string

当前生成的API方法为：

public getRawDocumentFileZipData(args: Array<DocumentMetadata>, observe?: 'body', reportProgress?: boolean): Observable<string>;

需要将返回类型从Observable<string>改为Observable<Uint8Array>或Observable<ArrayBuffer>。

解决方向 #

1. 调整OpenAPI响应定义 #

针对OpenAPI 3.x版本，推荐用content字段替代原有的schema，更精准声明二进制响应类型：

responses:
  200:
    description: The document file data as a zip file
    content:
      application/zip:
        schema:
          type: array
          items:
            type: integer
            format: uint8

这样生成工具会识别出这是Uint8Array类型的响应。如果需要ArrayBuffer，也可以将schema指定为type: string, format: binary并配合content字段，部分生成工具会自动映射为ArrayBuffer。

2. 配置代码生成工具规则 #

如果使用openapi-generator这类工具，可通过参数强制指定二进制响应的类型：

• 生成命令添加参数：--additional-properties=responseBinaryType=ArrayBuffer
• 或在配置文件openapi-generator-config.json中设置：

{
  "responseBinaryType": "ArrayBuffer"
}

针对Angular生成器，还可以开启supportsES6: true，确保生成的代码会使用responseType: 'arraybuffer'来处理响应。

3. 调用时手动指定响应类型（临时方案） #

如果无法修改OpenAPI定义或生成配置，调用API时可手动传入响应类型配置：

this.api.getRawDocumentFileZipData(args, 'body', true, { responseType: 'arraybuffer' })
  .subscribe((data: ArrayBuffer) => {
    const uint8Array = new Uint8Array(data);
    // 处理二进制数据
  });

注意：此方法需要确认生成的API方法支持传入额外的请求配置参数。

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