Swagger 2.0:如何指定'object'类型的输入参数

Question

使用Swagger 2.0我试图指定一个object类型的输入参数:

代码段:

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标题(produces在Swagger中).该标题与整个有效载荷有关.

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

目前,在指定表单参数时,您只能指定基元或基元数组.