Swagger 2.0: Come specificare un parametro di ingresso di tipo 'oggetto'

Question

Utilizzando Swagger 2.0 Sto cercando di specificare un parametro di ingresso del tipo di oggetto:

frammento di codice:

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 

Tuttavia il validatore è lamentarsi della parte type: object.

Come devo specificare correttamente i miei parametri di input?

Answer 1

Swagger consente di immettere gli oggetti solo come parametri del corpo.

Il motivo si riferisce al modo in cui il contenuto viene serializzato, che dipende dall'intestazione Content-Type (produces in Swagger). Questa intestazione si riferisce al carico utile nel suo complesso.

Quando si passano i parametri del modulo, si utilizzerà uno dei due tipi di mime: multipart/form-data o application/x-www-form-urlencoded. Mentre il primo ti permette di specificare un tipo mime per parte, Swagger attualmente non supporta tale definizione. C'è un biglietto aperto su di esso per consentirlo in una versione futura delle specifiche.

Attualmente, quando si specificano i parametri del modulo, è possibile specificare solo primitive o matrici di primitive.

Answer 2

OK, grazie all'input di @ron ho risolto la soluzione. Sì, ho bisogno di usare body invece di formData ma anche in quel caso non si è verificato, lamentando type: object. Ma se definisco prima l'oggetto, quindi $ref, allora tutto funziona. Il seguente codice si convalida.

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