通过 swagger 的二进制 API 文档

Question

I'm building an API that's able to upload multiple files at once. I need to document it through swagger, but I have no experience with it at all. My schema for the API is as follows:

The http request body is an octet-stream that looks like this. The first 4 bytes represents the number of packages, let the number of packages be n. The next 4*n bytes represents the sizes of the packages, where the first 4 bytes is the size of the first package, the next 4 is the size of the second package, etc. The end of the request simply consists of the packages.

An example would be: The packages \\xDE\\xAD\\xBE\\xEF and \\xFE\\xED\\xFA\\xCE\\xCA\\xFE\\xBE\\xEF , would compose the request:

\x00\x00\x00\x02||\x00\x00\x00\x04\x00\x00\x00\x08||\xDE\xAD\xBE\xEF\xFE\xED\xFA\xCE\xCA\xFE\xBE\xEF

I've tried documenting this in swagger like this:

 Batch:
      type: object
      properties:
        header:
          description: The number of packages represented in binary (big endian).
          type: string
          format: binary
          maxLength: 8
          minLength: 8
          example: \x00\x00\x00\x02
        subheader:
          description: The size of each package, where the size of the first package is represented by the first 4 bytes, the second by the next 4 bytes, etc (big endnian).
          type: string
          format: binary
          maxLength: 4294967295
          minLength: 0
          example: \x00\x00\x00\x04\x00\x00\x00\x04
        data:
          description: The data block for encryption/decryption
          type: string
          format: binary
          maxLength: 18446744073709551616
          minLength: 0
          example: \xDE\xAD\xBE\xEF\xDE\xAD\xBE\xEF

But it shows the request body as a json object (due to type: object ). Any ideas on how to do this properly?

Answer 1

Octet-stream request body is defined as a single binary string. There's no way to define the contents/format of specific fragments of the octet-stream. minLength and maxLength can be used to limit the size of the entire stream.

Also note that this is OpenAPI 3.0. OpenAPI 2.0 does not support application/octet-stream payloads (it only supports multipart/form-data ).

openapi: 3.0.2

paths:
  /something:
    post:
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              maxLength: 12345