Swagger 2.0：如何指定“对象”类型的输入参数

Question

使用 Swagger 2.0 我正在尝试指定对象类型的输入参数：

代码sn-p：

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

但是验证器抱怨type: object 部分。

我应该如何正确指定我的输入参数？

Answer 1

好的，感谢@ron 的输入，我已经找到了解决方案。是的，我需要使用body 而不是formData，但即便如此它也没有验证，抱怨type: object。但是，如果我先定义对象然后$ref 它那么一切正常。以下代码确实有效。

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

Answer 2

Swagger 仅允许将对象输入作为主体参数。

原因与内容的序列化方式有关，这取决于Content-Type 标头（Swagger 中的produces）。该标头与整个有效负载有关。

在传递表单参数时，您可以使用以下两种 mime 类型之一：multipart/form-data 或 application/x-www-form-urlencoded。虽然前者允许您为每个部分指定 mime 类型，但 Swagger 当前不支持这样的定义。上面有一张公开票，允许它在未来版本的规范中使用。

目前，在指定表单参数时，只能指定基元或基元数组。