Swagger UI：數組中的多個匿名對象

Question

我正在編寫一個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 

看着昂首闊步的描述請求機構的文件，也似乎沒有辦法處理的對象沒有名字。

我如何（使用YAML）在Swagger-UI中記錄這種類型的響應正文？

Answer 1

對象數組的定義如下：

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 

注意，架構定義的響應結構，這意味着你不需要（"Balance"，"AvailableBalance"等）的任何位置指定的實際值。但是，如果你想從您的文章（陣列2級的對象）作爲揚鞭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