如何在Swagger编辑器中将JSON对象作为多部分请求的一部分发送? [英] How to send a JSON object as part of a multipart request in Swagger Editor?

问题描述

我正在使用Swagger编辑器编写API文档，但是包含JSON对象的多部分POST请求有问题.这是我的Swagger YAML文件:

I'm writing API documentation using Swagger Editor, but having a problem with a multipart POST request containing a JSON object. Here is my Swagger YAML file:

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命令:

When I execute the request, I get the curl command like this:

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"}'

也就是说，body参数应该以键名param发送.

That is, the body parameter should be sent with the key name param.

推荐答案

multipart/*可以使用OpenAPI 3.0描述包含JSON对象的请求，但不能使用OpenAPI/Swagger 2.0描述.

multipart/* requests containing JSON objects can be described using OpenAPI 3.0 but not OpenAPI/Swagger 2.0.

OpenAPI 3.0本机支持 multipart/form-data 请求中的JSON对象:

OpenAPI 3.0 natively supports JSON objects in multipart/form-data requests:

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字符串的结构.

OpenAPI 2.0

In OpenAPI/Swagger 2.0, when consuming form data (application/x-www-form-urlencoded or multipart/form-data), form parameters whose value is a JSON string are described as just type: string, and you cannot define the structure of the JSON string.

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来代替:

To pass in a JSON object, the operation needs to consume application/json instead:

paths:
  /agent:
    post:
      consumes:
      - application/json  # <-----
      produces:
      - text/html
      parameters:
      - ...
      - in: body
        name: param
        description: parameter to send
        required: true
        schema:
          $ref: "#/definitions/Param"

这篇关于如何在Swagger编辑器中将JSON对象作为多部分请求的一部分发送?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！