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

基本上我返回一个名为＆＃34; response＆＃34;它包含两个变量：一个名为＆＃34; user＆＃34;的数组。包含几个字符串（为了清楚起见，我只包含两个字符串）和另一个变量（在＆＃34;用户＆＃34;数组之外），称为＆＃34; status＆＃34;包含整数。

上述代码无效，编辑通知我它不是一个有效的响应定义＆＃34;。

我不确定如何解决这个问题。我对自己做错了什么感到欣慰。

Answer 1

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

根据您的描述，响应应该如下（假设响应是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从其他地方引用。这样，例如，您可以在多个操作/响应中重用相同的模式。

      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将数组放在对象中

1 个答案: