Как описать данные динамической формы с помощью OpenAPI (Swagger)?

Я пытаюсь создать определение OpenAPI для этого запроса multipart/form-data:

curl -X POST \
  http://localhost:1234/api/v1/Submit \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -H 'sessionkey: kjYgfORsZ0GeiCls0FcR7w==' \
  -F item1=abc \
  -F item2=def
  -F item3=ghi
  ...

Мое определение API выглядит так:

post:
  consumes:
    - multipart/form-data
  produces:
    - application/json
  parameters:
    - in: formData
      name: item1
      type: string
    - in: formData
      name: item2
      type: string

Он отлично работает с фиксированными полями в formData.

Однако данные моей формы будут динамическими, и мне нужно иметь возможность отправлять произвольные ключи и значения.

Я попытался изменить параметры формы, чтобы использовать массив и additionalProperties, но это не дало желаемого результата:

- in: formData
  schema:
  additionalProperties:
    type: object

...

- in: formData
  type: array
  items:
    type: string

Можно ли определить динамические данные формы с разными ключами и значениями?


multipartform-data openapi swagger
person Dean    schedule 17.04.2018    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Данные динамической формы можно определить с помощью OpenAPI 3.0, но не OpenAPI 2.0 (Swagger 2.0). OpenAPI 2.0 поддерживает только фиксированные имена ключей в данных формы.

В OpenAPI 3.0 вы можете описать данные динамической формы, используя схему с additionalProperties:

openapi: 3.0.2
...
servers:
  - url: 'http://localhost:1234/api/v1'
paths:
  /Submit:
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              # Object properties correspond to form fields
              type: object
              additionalProperties:
                type: string
      responses:
        '200':
          description: OK


При тестировании запроса в пользовательском интерфейсе Swagger введите имена и значения полей в формате JSON:

{
  "field1": "value1",
  "field2": "value2",
  "field3": "value3"
}

Пользовательский интерфейс Swagger отправит эти значения в виде отдельных полей формы:

Отправка данных динамической формы в пользовательском интерфейсе Swagger

person Helen    schedule 17.04.2018
comment
Есть ли способ выразить произвольные ключи для multipart/form-data и format: binary, чтобы позволить пользователю загружать файлы с произвольными ключами? Я пытался с additionalProperties, но это не сработало. Он просто думал, что это струны. Проигнорировал format: binary. - person CMCDragonkai; 03.09.2020