如何用OpenAPI声明字节数组类型的application/octet-stream参数

要让OpenAPI代码生成工具输出接收原生字节数组（如Go的[]byte、Java的byte[]、C++的unsigned char[]）的API方法，需避开format: binary（生成文件对象）和type: object（生成通用对象）的错误写法，采用以下规范声明：

请求体场景 #

当接口需要接收application/octet-stream格式的二进制请求体时，直接将schema的type设为string并指定format: byte，同时关联application/octet-stream内容类型：

paths:
  /binary/upload:
    post:
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: byte
      responses:
        '200':
          description: 上传成功

响应体场景 #

如果接口返回application/octet-stream格式的二进制数据，声明方式类似：

paths:
  /binary/download:
    get:
      responses:
        '200':
          description: 二进制数据响应
          content:
            application/octet-stream:
              schema:
                type: string
                format: byte

关键说明 #

• format: byte是OpenAPI规范中对应字节序列的标准声明，结合application/octet-stream类型后，代码生成工具会自动将其转换为目标语言的原生字节数组类型，而非Base64字符串。
• format: binary被OpenAPI定义为文件类型，会触发生成文件操作相关的对象（如Java的MultipartFile、Go的*os.File），不符合字节数组需求。
• type: object会让工具生成通用对象类型（如Go的map[string]interface{}、Java的Object），完全偏离二进制数据的处理逻辑。

内容的提问来源于stack exchange，提问作者Marc Le Bihan