Swagger UI:数组中有多个匿名对象

jpfvwuh4  于 2022-11-06  发布在  其他
关注(0)|答案(2)|浏览(184)

我正在为一个API编写Swagger文档,一个端点返回许多嵌套的对象和参数。
但是,有一个返回的数组并不返回常规参数,而是返回两个保存参数的匿名对象。

"balanceDisplaySettings": [ 
  {
    "type": "Balance",
    "label": "Current",
    "visible": true,
    "primary": false
  },
  {
    "type": "AvailableBalance",
    "label": "Available",
    "visible": true, 
    "primary": true
  }
]

YAML语言

swagger: '2.0'
schemes:
 - https
consumes:
  - application/json
produces:
  - application/json
paths:
"/Path/":
     responses:
     '200':
      description: OK
      schema:
        type: object
        properties:
          balanceDisplaySettings:
            type: array
            items:
              type: object
              properties:
                type:
                  type: "Balance"
                  description: description
                label: 
                  type: "Available"
                  description: description
                visible:
                  type: boolean
                  description: description
                primary:
                  type: boolean
                  description: description
              type: object
              properties:
                type:
                  type: "AvailableBalance"
                  description: description
                label: 
                  type: "Available"
                  description: description
                visible: 
                  type: boolean
                  description: description
                primary:
                  type: boolean
                  description: description

看看swagger的文档中关于描述请求体的内容,似乎没有办法处理没有名称的对象。
我如何(使用YAML)在Swagger-UI中记录这种类型的响应正文?

svgewumm

svgewumm1#

对象数组的定义如下:

type: array
items:
  type: object
  properties:
    prop1:
      type: string
    prop2:
      type: integer
    # etc.

在您的示例中,响应包含一个具有balanceDisplaySettings属性的对象,而此属性包含一个对象数组。这可以定义如下:

paths:
  /Path:
    get:
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              balanceDisplaySettings:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    label: 
                      type: string
                    visible:
                      type: boolean
                    primary:
                      type: boolean

请注意,模式定义了response structure,这意味着您不需要在任何地方指定实际值("Balance""AvailableBalance"等)。但是,如果您希望将帖子中的示例(包含2个对象的数组)显示为Swagger UI中的示例,则可以如下添加:

balanceDisplaySettings:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    label: 
                      type: string
                    visible:
                      type: boolean
                    primary:
                      type: boolean
                example:            # <-- example of array of 2 objects
                  - type: Balance
                    label: Current
                    visible: true
                    primary: false
                  - type: AvailableBalance
                    label: Available
                    visible: true
                    primary: true

最后,您可能希望拆分内联嵌套架构,以使规范更加模块化。

paths:
  /Path:
    get:
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/MyResponseObject'
                                    #   |
definitions:                        #   |
  # TODO: better name               #   |
  MyResponseObject:    # <--------------+
    type: object
    properties:
      balanceDisplaySettings:
        type: array
        items:
          $ref: '#/definitions/BalanceDisplaySetting'
        example:                     #  |
          - type: Balance            #  |
            label: Current           #  |
            visible: true            #  |
            primary: false           #  |
          - type: AvailableBalance   #  |
            label: Available         #  |
            visible: true            #  |
            primary: true            #  |
                                     #  |
  BalanceDisplaySetting:     # <--------+
    type: object
    properties:
      type:
        type: string
        example: Balance
      label:
        type: string
        example: Current
      visible:
        type: boolean
      boolean:
        type: boolean
e5nqia27

e5nqia272#

另一个解决方案是oneOF参数,通过它,您可以根据需要使用多个匿名对象。
只需创建一些定义并在items中调用它们:

"type": "array",
"items": {
  "oneOf": [
    { "$ref": "#/components/schemas/Schema1" },
    { "$ref": "#/components/schemas/Schema2" }
  ]
}

您可以在此处阅读更多信息:
https://community.smartbear.com/t5/Swagger-Open-Source-Tools/Can-You-Define-a-Response-Consisting-of-an-Array-With-Two/td-p/186919
希望能有所帮助

相关问题