使用 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

基本上我 return 一个名为 "response" 的对象包含两个变量：一个名为 "user" 的数组包含多个字符串（为了清楚起见我只包含两个）和另一个名为 "status" 的变量（在 "user" 数组之外）包含一个整数。

上面的代码不起作用，编辑器通知我它不是 "valid response definition"。

我不确定如何解决这个问题。对于我做错的事情，我将不胜感激。

Answer 1

Basically I return an object called "response" that contains two variables: An array called "user" that contains several strings (I included just two for the sake of clarity) and another variable (outside of the "user" array) called "status" that contains an integer.

根据您的描述，回复应该如下（假设回复为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

为方便起见，可以将具有嵌套对象的复杂模式分解为单独的对象模式。模式可以写在全局 definitions 部分，并通过 $ref 从其他地方引用。这样，例如，您可以在多个 operations/responses.

中重复使用相同的模式

      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

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

Putting arrays inside of objects using Swagger 2.0 and YAML

yaml

swagger

swagger-2.0