响应中的 Swagger OpenAPI 数组文档

Question

如何将这样的 Json 大摇大摆地记录在响应部分中？

{
    "data": [{
        "id": "",
        "name": "James",
        "chat": "1",
        "messages": {
            "current": null,
            "count": null,
            "length": null,
            "rows": null,
            "type": null
        },
        "cid": "204",
        "cat": "messages",
        "mark": false
    }],
    "total": 200,
    "action": "success"
}

我试过了

responses:
        '200':
          description: test data
          content:
            application/json:
              schema:
                example:
                  - id: null
                     name:  James
                      chat: 1
                        messages:
                         current:
                         count:
                         length: 
                         rows:
                         type:
                      cid: 204
                      cat: chat
                      mark: false
                  totalCount: 200
                  action: success

但显示error bad indentation of a mapping entry

Answer 1

您必须在 #/components/schemas 部分将预期的对象结构定义为单独的架构。

例如，您将生成的模型命名为 ResponseObj，它具有属性 data、total 和 action。 data 属性是另一种具有自己属性的复杂类型，因此您还为该类型定义了一个模型。这一直持续到您将所有模型定义为简单的属性类型。

这里是你的例子的定义：

components:
  schemas:
    ResponseObj:
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/DataObj'
          total:
            type: string
          action:
            type: string
    DataObj:
        properties:
          id:
            type: string
          name:
            type: string
          chat:
            type: string
          messages:
            type: array
            items:
              $ref: '#/components/schemas/MessageObj'
          cid:
            type: number
          cat:
            type: string
          mark:
            type: boolean
    MessageObj:
        properties:
          current:
            type: string
          count:
            type: string
          length:
            type: number
          rows:
            type: number
          type:
            type: string

现在您可以参考 ResponseObj 模型作为您操作的预期结果：

paths:
  /example:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObj'

响应中的 Swagger OpenAPI 数组文档

Swagger OpenAPI array documentation in response

swagger

swagger-ui

openapi