Swagger 2.0: Wie ein Eingabeparameter des Typs ‚Objekt‘ spezifizieren

Question

Mit Swagger 2.0 Ich versuche, ein Eingabeparameter des Typs Objekt angeben:

Code-Schnipsel:

paths: 
    '/thingies/{thingy_id}.json': 
    put: 
     summary: Update an existing thingy 
     description: Updates an existing thingy 
     parameters: 
     - name: thingy_id 
      description: ID of the thingy to update 
      in: path 
      required: true 
      type: integer 
     - name: translation 
      description: Name and Locale for new translation 
      in: formData 
      type: object 
      properties: 
      name: 
       type: string 
      locale: 
       type: string 

jedoch der Prüfer ist sich über den type: object Teil beschwert.

Wie soll ich meine Eingabeparameter richtig angeben?

Answer 1

Swagger ermöglicht Objekteingaben nur als Körperparameter.

Der Grund dafür bezieht sich auf die Art und Weise, wie Inhalt serialisiert wird, die von der Content-Type Kopfzeile abhängt (produces in Swagger). Dieser Header bezieht sich auf die Nutzlast als Ganzes.

Wenn Sie Formularparameter übergeben, verwenden Sie einen von zwei MIME-Typen: multipart/form-data oder application/x-www-form-urlencoded. Während die erstere es erlaubt, einen Mime-Typ pro Teil anzugeben, unterstützt Swagger derzeit keine solche Definition. Es gibt ein offenes Ticket, um es in einer zukünftigen Version der Spezifikation zuzulassen.

Derzeit können Sie bei der Angabe von Formularparametern nur Primitive oder Arrays von Primitiven angeben.

Answer 2

Okay, dank der Eingabe von @ron habe ich die Lösung ausgearbeitet. Ja, ich muss body anstelle von formData verwenden, aber selbst dann hat es nicht validiert und beschwert sich über type: object. Aber wenn ich das Objekt zuerst dann $ref es dann alles funktioniert. Der folgende Code überprüft.

swagger: '2.0' 
info: 
    version: '1' 
    title: Thingy Service 
    description: Everyone loves their thingy 
schemes: 
    - http 
consumes: 
    - application/json 
produces: 
    - application/json 

definitions: 
    localisation: 
    type: object 
    required: 
     - name 
     - locale 
    properties: 
     name: 
     type: string 
     locale: 
     type: string 

paths: 
    '/thingies/{thingy_id}.json': 
    put: 
     summary: Update an existing thingy 
     description: Updates an existing thingy 
     parameters: 
     - name: thingy_id 
      description: ID of the thingy to update 
      in: path 
      required: true 
      type: integer 
     - name: translation 
      description: Name and Locale for new translation 
      in: body 
      schema: 
      $ref: '#/definitions/localisation' 
     responses: 
     204: 
      description: No data 
     404: 
      description: Thingy not found