¿Cómo gestiona OpenAPI los datos binarios y las descargas de archivos? #

No todas las respuestas de una API son objetos JSON. Muchas API necesitan servir datos binarios: archivos descargables, imágenes, PDF, exportaciones, archivos comprimidos y flujos de bytes sin procesar. Del mismo modo, muchas API aceptan la subida de archivos como parte de su entrada. OpenAPI ofrece convenciones específicas para describir estos casos, y comprenderlas es esencial para documentar con precisión las operaciones de API centradas en archivos.

Tipos de contenido de respuesta para datos binarios #

La clave para describir respuestas binarias en OpenAPI es la combinación del tipo de medio de content y el format del schema. En las descargas de archivos binarios, el tipo de medio indica qué clase de archivo se devuelve, y el esquema utiliza type: string con format: binary:

paths:
  /reports/{reportId}/download:
    get:
      summary: Download a report as a PDF
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The report PDF file
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Attachment disposition with filename
              example: 'attachment; filename="report-2026.pdf"'
            Content-Length:
              schema:
                type: integer
              description: Size of the file in bytes
          content:
            application/pdf:
              schema:
                type: string
                format: binary

format: binary indica que la cadena representa datos binarios sin procesar (una secuencia de bytes), no una cadena de texto. Las herramientas entienden que esto significa que el cuerpo de la respuesta es el contenido sin procesar del archivo, no un valor codificado en JSON.

Tipos de medio habituales para descargas de archivos #

Los distintos tipos de archivo utilizan diferentes tipos de medio en la clave content:

responses:
  "200":
    description: File download
    content:
      application/pdf:           # PDF documents
        schema:
          type: string
          format: binary
      application/zip:           # ZIP archives
        schema:
          type: string
          format: binary
      image/png:                 # PNG images
        schema:
          type: string
          format: binary
      image/jpeg:                # JPEG images
        schema:
          type: string
          format: binary
      application/octet-stream:  # Generic binary (unknown type)
        schema:
          type: string
          format: binary
      text/csv:                  # CSV exports (text-based)
        schema:
          type: string

application/octet-stream es el tipo de medio binario genérico que se utiliza cuando el tipo de contenido no se conoce de antemano o cuando se pretende una descarga binaria genérica.

Varios tipos de contenido (negociación de contenido) #

Algunos endpoints pueden devolver un archivo en varios formatos según lo que solicite el cliente. Esto se expresa mediante varias entradas dentro de content:

paths:
  /users/export:
    get:
      summary: Export the user list
      responses:
        "200":
          description: User list export
          content:
            text/csv:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary

El cliente utiliza el encabezado de solicitud Accept para indicar qué formato prefiere. El servidor responde con el tipo de contenido correspondiente.

Documentar el encabezado Content-Disposition #

Los endpoints de descarga de archivos suelen establecer el encabezado Content-Disposition para indicar al navegador (o al cliente HTTP) que trate la respuesta como un archivo adjunto con un nombre de archivo concreto. Este encabezado debe documentarse en la respuesta de OpenAPI:

responses:
  "200":
    description: Downloaded file
    headers:
      Content-Disposition:
        description: Instructs the client to download the response as a named file
        schema:
          type: string
        example: 'attachment; filename="export-2026-04-30.csv"'
      Content-Type:
        description: MIME type of the file
        schema:
          type: string
        example: text/csv

Subida de archivos con multipart form data #

Los endpoints de subida de archivos suelen utilizar multipart/form-data como tipo de contenido del cuerpo de la solicitud. En OpenAPI, esto se expresa con el objeto requestBody y un tipo de medio multipart/form-data:

paths:
  /documents:
    post:
      summary: Upload a document
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                name:
                  type: string
                  description: Optional display name for the document
                  example: "Q4 Report"
                tags:
                  type: array
                  items:
                    type: string
                  description: Classification tags
      responses:
        "201":
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'

La propiedad file utiliza type: string con format: binary. Esto indica a las herramientas y a los generadores de código que este campo del formulario representa un archivo binario, no un valor de texto.

Metadatos de codificación para campos multipart #

Para un control más preciso de la codificación multipart, como establecer el tipo de contenido de una parte concreta o especificar que un arreglo (array) debe enviar partes separadas, utiliza el objeto encoding en el tipo de medio:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          profileImage:
            type: string
            format: binary
          metadata:
            type: object
            properties:
              description:
                type: string
      encoding:
        profileImage:
          contentType: image/png, image/jpeg
        metadata:
          contentType: application/json

El objeto encoding permite que la especificación declare explícitamente qué tipos de contenido son válidos para cada parte de una solicitud multipart.

Datos binarios codificados en base64 #

Algunas API transmiten datos binarios incrustados en respuestas JSON mediante codificación base64. En OpenAPI, esto se expresa con type: string y format: byte (no format: binary):

components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
          format: byte
          description: Base64-encoded file content
        mimeType:
          type: string
          example: application/pdf

La distinción entre format: binary y format: byte es importante:

• format: binary: datos binarios sin procesar en el cuerpo HTTP (descarga o subida de archivos)
• format: byte: datos binarios codificados en base64 e incrustados dentro de un formato de texto (por ejemplo, JSON)

Documentar las restricciones de tamaño de archivo #

Cuando un endpoint de subida de archivos aplica límites de tamaño, documéntalo en description y, si utilizas OpenAPI 3.1, en el contentEncoding del esquema o mediante maxLength:

properties:
  file:
    type: string
    format: binary
    description: "The file to upload. Maximum size: 10 MB. Accepted formats: PDF, DOCX, XLSX."

Las restricciones explícitas de tamaño y formato en las descripciones ayudan a los desarrolladores a comprender los límites sin tener que descubrirlos a través de errores.

Consideraciones sobre la generación de código #

Los generadores de código tratan de forma especial los campos con format: binary:

• En los clientes TypeScript generados, los campos de subida binaria se convierten en tipos File | Blob
• En los clientes Python generados, se convierten en tipos IO[bytes] o bytes
• En los clientes Java generados, se convierten en tipos java.io.File o byte[]
• Las operaciones de descarga devuelven objetos bytes, Buffer o Stream, según el lenguaje

Un endpoint binario bien documentado produce código de cliente generado utilizable. Si falta la anotación format: binary, el cliente generado trata el campo como una cadena simple, lo que rompe la funcionalidad de subida y descarga.

Conclusión #

OpenAPI gestiona los datos binarios mediante la combinación de tipos de medio adecuados (application/pdf, image/jpeg, application/octet-stream, multipart/form-data) y formatos de esquema (format: binary para datos binarios sin procesar y format: byte para contenido codificado en base64). Documentar los encabezados Content-Disposition, los límites de tamaño de archivo, los formatos aceptados y los detalles de codificación produce una documentación de API precisa y utilizable, así como clientes generados de alta calidad que gestionan correctamente la subida y la descarga de archivos desde la primera compilación.

Última actualización: 30 de abril de 2026.