Swagger编辑器不发送身体参数的密钥

Question

我开始用swagger编写API的文档。我有这个问题。这是我的摇摆者json。

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 -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'发送身体参数。

Answer 1

在所述OpenAPI /扬鞭2.0，消耗形式的数据（application/x-www-form-urlencodedmultipart/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" 

这将在即将到来的OpenAPI Specification 3.0，在那里将可能have JSON objects in 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: 
     ...