Question

我刚刚开始使用swagger-editor来定义我的RESTful API，而且我对这些回复感到困惑。我的许多方法只返回一个整数数组，而我不理解如何在YAML中指定它。

Answer 1

OpenAPI（fka Swagger）规范2.0使用JSON Schema v4的子集。您可以参考JSON Schema docs或this great guide来了解如何使用JSON Schema描述不同的数据类型。但请记住，在OpenAPI / Swagger中，JSON Schema的某些功能不受支持或工作方式不同。规范mentions究竟支持什么。

回到你的问题，一个整数数组被定义为：

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

整数返回类型的Swagger数组

1 个答案: