Swagger 2.0: Jak określić parametr wejściowy typu „obiektu”

Question

Korzystanie Swagger 2,0 Próbuję określić parametr wejściowy typu obiektu:

fragment kodu:

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 

Jednak Validator jest narzekać na część type: object.

Jak poprawnie określić parametry wejściowe?

Answer 1

Swagger zezwala na wejścia obiektu tylko jako parametry bryły.

Powodem tego jest sposób serializowania treści, która zależy od nagłówka Content-Type (produces w Swagger). Ten nagłówek odnosi się do ładunku jako całości.

Podczas przekazywania parametrów formularza można użyć jednego z dwóch typów MIME: multipart/form-data lub application/x-www-form-urlencoded. Podczas gdy pierwsza pozwala na określenie typu mime na część, Swagger obecnie nie obsługuje takiej definicji. Jest na nim otwarty bilet, aby umożliwić go w przyszłej wersji specyfikacji.

Obecnie podczas określania parametrów formularza można określać tylko prymitywy lub tablice prymitywów.

Answer 2

OK, dzięki wprowadzeniu z @ron wypracowałem rozwiązanie. Tak, potrzebuję użyć body zamiast formData, ale nawet wtedy nie sprawdziłem, narzekając na type: object. Ale jeśli najpierw zdefiniuję obiekt, wtedy to wszystko działa. Poniższy kod sprawdza poprawność.

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