Как отправить объект JSON как часть составного запроса в редакторе Swagger?

Я пишу документацию по API с помощью редактора Swagger, но у меня проблема с многостраничным запросом POST, содержащим объект JSON. Вот мой YAML-файл Swagger:

swagger: '2.0'
info:
  version: 1.0.0
  title: Documentation API
paths:
  /agent:
    post:
      consumes:
      - multipart/form-data
      produces:
      - text/html
      parameters:
      - in: query
        name: method
        description: name of method to access
        required: true
        type: string
      - in: body
        name: param
        description: parameter to send
        required: true
        schema:
            $ref: "#/definitions/Param"
      responses:
        201:
          description: item created
        400:
          description: invalid input, object invalid
        409:
          description: an existing item already exists
definitions:
  Param:           # <----------
    type: object
    required:
      - username
      - password
      - imsi
      - imei
      - deviceId
    properties:
      username:
        type: string
      password:
        type: string
      imsi:
        type: string
      imei:
        type: string
      deviceId:
        type: string  
host: 'localhost'
basePath: /v1/api
schemes:
  - https

Когда я выполняю запрос, я получаю такую ​​команду curl:

curl -X POST "https://localhost/v1/api/agent?method=login" -H  "accept: text/html" -H  "content-type: multipart/form-data" -F {"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}

но я ожидаю получить вот это:

curl -X POST "https://localhost/v1/api/agent?method=login" -H  "accept: text/html" -H  "content-type: multipart/form-data" -F 'param={"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}'

То есть параметр тела должен быть отправлен с именем ключа param.


openapi swagger-2.0 swagger-editor
person Ari Ejawinata Ginting    schedule 02.06.2017    source источник

Ответы (1)


arrow_upward
6
arrow_downward

multipart/* запросы, содержащие объекты JSON, можно описать с помощью OpenAPI 3.0, но не OpenAPI / Swagger 2.0.

OpenAPI 3.0

OpenAPI 3.0 изначально поддерживает Объекты JSON в multipart/form-data запросах:

paths:
  /agent:
    post:
      parameters:
      - in: query
        name: method
        description: name of method to access
        required: true
        schema:
          type: string

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:

                # Here, "param" is part/parameter name in a multipart payload.
                # Parameter value is an object defined by the "Param" schema.
                # Default Content-Type for objects is application/json.
                param:
                  $ref: "#/components/schemas/Param"
      responses:
        ...

OpenAPI 2.0

В OpenAPI / Swagger 2.0 при использовании данных формы (application/x-www-form-urlencoded или multipart/form-data) параметры формы, значение которых является строкой JSON, описываются как просто type: string, и вы не можете определить структуру строки JSON.

paths:
  /agent:
    post:
      consumes:
      - multipart/form-data
      produces:
      - text/html
      parameters:
      - ...
      - in: formData    # <-------
        name: param
        description: parameter to send
        required: true
        type: string    # <-------

Чтобы передать объект JSON, операция должна вместо этого использовать application/json:

paths:
  /agent:
    post:
      consumes:
      - application/json  # <-----
      produces:
      - text/html
      parameters:
      - ...
      - in: body
        name: param
        description: parameter to send
        required: true
        schema:
          $ref: "#/definitions/Param"
person Helen    schedule 02.06.2017
comment
+1 и больше примеров requestBody появились теперь, когда вышла версия 3.0 . - person danwild; 23.09.2018