Бинарная документация по API через сваггер - PullRequest
Новая
       21

Бинарная документация по API через сваггер

0 голосов
/ 28 января 2020

Я создаю API, который может загружать несколько файлов одновременно. Мне нужно документировать это через чванство, но у меня нет никакого опыта с этим вообще. Моя схема для API выглядит следующим образом:

Тело http-запроса - это поток октетов, который выглядит следующим образом. Первые 4 байта представляют количество пакетов, пусть количество пакетов равно n. Следующие 4 * n байтов представляют размеры пакетов, где первые 4 байта - это размер первого пакета, следующие 4 - это размер второго пакета, et c. Конец запроса просто состоит из пакетов.

Примером может быть: Пакеты \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). Любые идеи о том, как сделать это правильно?

1 Ответ

1 голос
/ 28 января 2020

Тело запроса октетного потока определяется как одна двоичная строка. Нет способа определить содержимое / формат указанных c фрагментов потока октетов. 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
...