如何在Swagger中输入JSON对象数组？

Question

目前使用Swagger.io来记录我的API。试图了解如何文档发送自定义json对象。

• 将一个集合放到/ some_endpoint

• MIME：application / json

• 自定义数据：

  [
    {"keyA": "a value", "keyB": "b value"},
    {"keyA": "a value", "keyB": "b value"}
  ]
  

是否可以在Swagger中记录这一点？

/some_endpoint:
    put:
      description: |
        desc goes here
      parameters:
        - name: guid
          in: query
          description:
          required: true
          type: string
          format: string          
      # Expected responses for this operation
      responses:
        # Response code
        200:
          description: Successful response

Answer 1

JSON数据在请求正文中发送，因此需要将其定义为body parameter。使用schema关键字（不是type）描述了正文结构。在您的示例中，数据是一个对象数组，其中每个对象都具有属性keyA和keyB。

paths:
  /some_endpoint:
    put:
      summary: Puts something
      description: |
        desc goes here
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/MyObject'
            # If you need to define array size constraints:
            minItems: 1
            minItems: 10

definitions:
  MyObject:
    type: object
    properties:
      keyA:
        type: string
      keyB:
        type: string
    # If keyA and keyB are required:
    required:
      - keyA
      - keyB

要指定请求数据是JSON，请在操作级别使用consumes键。如果您的所有API操作都使用JSON，则可以在规范的根级别添加consumes。