如何在 Swagger 编辑器中将 JSON 对象作为多部分请求的一部分发送？

Question

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

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

也就是说， body 参数应该与键 name 一起发送param。

Answer 1

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

开放API 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:
        ...

开放API 2.0

在 OpenAPI/Swagger 2.0 中，在消费表单数据（application/x-www-form-urlencoded或multipart/form-data）时，值为 JSON 字符串的表单参数被描述为 just 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"