使用Swagger 2.0和YAML将数组放入对象内部

Question

我目前正在学习如何使用Swagger文档，因为我的公司正在评估使用它作为即将到来的项目文档的标准方式。

我在网上读到，使用YAML比使用JSON更容易阅读，而且由于YAML是JSON的一个子集，所以我认为这是可以的。

我正在处理200代码的响应，我想表示类似于以下结构的内容：

responses:
    200:
      description: OK.
      schema:
        title: response
        type: object
        items:
          properties:
            title: user
            type: array
            items:
                id:
                  type: string
                name:
                  type: string
            status:
              type: integer

基本上，我返回一个名为“响应”的对象，它包含两个变量：一个名为“用户”的数组，它包含几个字符串（为了清晰起见，我只包含了两个），另一个变量（在“用户”数组之外），名为“状态”，它包含一个整数。

上面的代码不起作用，编辑器通知我它不是“有效的响应定义”。

我不知道如何解决这个问题。如果你能帮我做错事，我将不胜感激。

Answer 1

基本上，我返回一个名为“响应”的对象，它包含两个变量：一个名为“用户”的数组，它包含几个字符串（为了清晰起见，我只包含了两个），另一个变量（在“用户”数组之外），名为“状态”，它包含一个整数。

根据您的描述，响应应该如下所示（假设响应是JSON）。基本上，您有一个具有嵌套对象的对象：

{
  "user": {
    "id": "12345",
    "name": "Alice"
  },
  "status": 0
}

该响应可定义如下：

      responses:
        200:
          description: OK.
          schema:
            title: response
            type: object
            required: [user, status]
            properties:
              user:
                type: object
                required: [id, name]
                properties:
                  id:
                    type: string
                  name:
                    type: string
              status:
                type: integer

为了方便起见，具有嵌套对象的复杂模式可以分解为单个对象模式。模式可以在全局定义部分中编写，并通过$ref从其他地方引用。例如，通过这种方式，您可以在多个操作/响应中重用相同的模式。

      responses:
        200:
          description: OK.
          schema:
            $ref: "#/definitions/ResponseModel"

definitions:
  ResponseModel:
    title: response
    type: object
    properties:
      user:
        $ref: "#/definitions/User"
      status:
        type: integer
    required:
      - user
      - status

  User:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
    required:
      - id
      - name