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: 
     ...