如何提供一個包含數組作爲其屬性的數組中的對象定義的示例

Question

參考下面的示例，我想在其定義中提供一個NamedElementArray的示例。這將需要爲elements屬性顯示一個NamedElement數組的示例。

我該怎麼做？我找不到在swagger規範中如何做到這一點的細節。

swagger: '2.0' 

info: 
    version: "0.0.0" 
    title: Example 

definitions: 
    Identifier: 
    type: string 
    format: uuid 
    NamedElement: 
    type: object 
    properties: 
     name: 
     type: string 
     identifier: 
     $ref: "#/definitions/Identifier" 
    required: 
    - name 
    - identifier 
    example: 
     name: Identifier1 
     identifier: ab804529-11d0-4781-a49a-3bbbc40243df 
    NamedElementArray: 
    type: object 
    properties: 
     name: 
     type: string 
     elements: 
     type: array 
     minLength: 0 
     items: 
      $ref: "#/definitions/NamedElement" 
    required: 
    - name 
    - elements 
    example: 
     name: Fred 
     elements: 

paths: 
    /elements/{name}: 
    get: 
     description: | 
     Gets `NamedElement` objects, based on the **name** query param. 
     parameters: 
     - 
      name: name 
      in: path 
      description: Name of element array to return 
      required: true 
      type: string 
     responses: 
     200: 
      description: Returns a named element array 
      schema: 
      $ref: "#/definitions/NamedElementArray" 
     default: 
      description: Return nothing 

Answer 1

你有高水平實例和低水平者之間做出選擇。 在Swagger UI中，高級示例在本地之前。

上Swagger Hub

提供完整的示例，您可以定義每個屬性（低電平）爲例：

Identifier: 
    type: string 
    format: uuid 
    example: Local UUID example 

NamedElement: 
    type: object 
    properties: 
     name: 
      type: string 
      example: Local identifier example 
     identifier: 
      $ref: "#/definitions/Identifier" 
     required: 
      - name 
      - identifier 

NamedElementArray: 
    type: object 
    properties: 
     name: 
      type: string 
      example: Local name example 
     elements: 
      type: array 
      minLength: 0 
      items: 
       $ref: "#/definitions/NamedElement" 
    required: 
     - name 
     - elements 

在這種情況下，例如將看起來像這樣在揚鞭UI：

{ 
    "name": "Local name example", 
    "elements": [ 
    { 
     "name": "Local identifier example", 
     "identifier": "Local UUID example" 
    } 
    ] 
} 

但是你也可以舉一個完整的例子，就像你在上的例子那樣：

NamedElementArray: 
    type: object 
    properties: 
     name: 
      type: string 
     elements: 
      type: array 
      minLength: 0 
      items: 
       $ref: "#/definitions/NamedElement" 
    required: 
     - name 
     - elements 
    example: 
     name: Fred 
     elements: 
      - name: Identifier1 
       identifier: ab804529-11d0-4781-a49a-3bbbc40243df 
      - name: Identifier2 
       identifier: zzz4529-11d0-4781-a49a-3bbbc40243df 

在這種情況下，例如將看起來像這樣在揚鞭UI：

{ 
    "name": "Fred", 
    "elements": [ 
    { 
     "name": "Identifier1", 
     "identifier": "ab804529-11d0-4781-a49a-3bbbc40243df" 
    }, 
    { 
     "name": "Identifier2", 
     "identifier": "zzz4529-11d0-4781-a49a-3bbbc40243df" 
    } 
    ] 
}