Swagger Editor sendet keinen Schlüssel des Körperparameters

Question

Ich beginne, Dokumentation der API mit Hilfe von Swagger zu schreiben. Ich habe ein Problem damit. Hier ist mein Swagger 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 

Wenn ich ausgeführt habe, bekomme ich die Curl so.

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

aber Curl erwartet so.

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

Ich brauche Körper Parameter mit Schlüssel 'param' gesendet.

Answer 1

In OpenAPI-/Swagger 2.0, wenn Formulardaten raubend (application/x-www-form-urlencoded oder multipart/form-data), Formparameter, dessen Wert eine JSON Zeichenfolge als gerade type: string beschrieben, und man kann die Struktur des JSON String nicht definieren.

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

Um in einem JSON-Objekt übergeben, die Operation application/json verbrauchen muss:

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

Dies wird in den kommenden OpenAPI Specification 3.0 geändert werden, wo es möglich have JSON objects in multipart/form-data Anfragen werden:

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