通过 swagger 的二进制 API 文档

Question

我正在构建一个能够一次上传多个文件的 API。我需要通过招摇来记录它，但我根本没有这方面的经验。我的 API 架构如下：

http 请求正文是一个八位字节流，如下所示。前4个字节代表包数，设包数为n。接下来的 4*n 个字节表示包的大小，其中前 4 个字节是第一个包的大小，接下来的 4 个字节是第二个包的大小，等等。请求的末尾仅包含包。

例如：包 \xDE\xAD\xBE\xEF 和 \xFE\xED\xFA\xCE\xCA\xFE\xBE\xEF 将组成请求：

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

我试过像这样大摇大摆地记录这个：

 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

但是它将请求正文显示为 json 对象（由于 type: object）。关于如何正确执行此操作的任何想法？

Answer 1

八位字节流请求正文定义为单个二进制字符串。无法定义八位字节流的特定片段的 contents/format。 minLength和maxLength可以用来限制整个流的大小。

另请注意，这是 OpenAPI 3.0。 OpenAPI 2.0 不支持 application/octet-stream 有效负载（它仅支持 multipart/form-data）。

openapi: 3.0.2

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

通过 swagger 的二进制 API 文档

Binary API documentation via swagger

api

documentation

binary

http

swagger