整数返回类型的Swagger数组

Question

我刚刚开始使用swagger-editor来定义我的RESTful API,我对这些响应感到困惑.我的许多方法只返回一个整数数组,我不知道如何在YAML中指定它.

Answer 1

OpenAPI(fka Swagger)规范2.0使用JSON Schema v4的子集.您可以参考JSON Schema文档或本指南,了解如何使用JSON Schema描述不同的数据类型.但请记住,在OpenAPI/Swagger中,JSON Schema的某些功能不受支持或工作方式不同.规范提到了究竟支持的内容.

回到你的问题,一个整数数组定义为:

type: array
items:
  type: integer

或者在回复的背景下:

paths:
  /something:
    get:
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: integer

如果在规范中的多个位置使用整数数组,则可以在全局definitions部分中定义数组,然后使用$ref它来引用它:

paths:
  /something:
    get:
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/ArrayOfInt"

definitions:
  ArrayOfInt:
    type: array
    items:
      type: integer

您还可以指定example数组的值.Swagger UI将显示此示例,并且一些模拟工具将在生成示例响应时使用它.

definitions:
  ArrayOfInt:
    type: array
    items:
      type: integer
    example: [1, 2, 3, 4]
    # Make sure to put the multi-item "example"
    # on the same level as the "type" and "items" keywords