使用 Swagger 将数组指定为参数

Posted 2023-02-26

【中文标题】使用 Swagger 将数组指定为参数

【英文标题】：Specify an array as a parameter with Swagger

【发布时间】：2017-01-28 13:10:11

【问题描述】：

如何将数组指定为参数？例如，可以给 /persons 的帖子提供字符串 username、firstname 和 lastname，和数组 myArray。

paths:
  /persons:
    post:
      parameters:
        - name: person_what_is_the_purpose_of_this
          in: body
          description: The person to create.
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
              myArray:
                type: array
                  items:
                    properties:
                      myArrayElement:
                        type: string
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

【参考方案1】：

您需要指定collectionFormat: multi

对于您的数组，它看起来像这样，请确保将其放在与类型相同的级别：

myArray:
  type: array
  collectionFormat: multi

Documentation about arrays

【参考方案2】：

swagger: "2.0"
info:
  version: "1.0.0"
  title: Swagger Petstore
host: petstore.swagger.io
basePath: /v2
schemes:
  - http
paths:
  /pets/findByStatus:
    get:
      parameters:
        - in: query
          name: status
          type: array
          items:
            type: string
      responses:
        "200":
          description: successful operation
          schema:
            type: array
            items:
              type: object
              required:
                - name
                - photoUrls
              properties:
                id:
                  type: integer
                  format: int64
                category:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                name:
                  type: string
                  example: doggie
                photoUrls:
                  type: array
                  items:
                    type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        format: int64
                      name:
                        type: string
        "400":
          description: Invalid status value

【讨论】：

这是发送一个列表，而不是一个数组