Swagger UI：配列内の複数の匿名オブジェクト

Question

API用のSwaggerドキュメントを作成しており、1つのエンドポイントが多数のネストされたオブジェクトとパラメータを返します。

しかし、返された配列は1つありますが、これは通常のパラメータを返しません。代わりに、パラメータを保持する2つの匿名オブジェクトを返します。リクエストボディの記述のための闊歩のドキュメントを見てみると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 

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

は、一見名前のないオブジェクトを処理する方法はありません。

Swagger-UIでこのタイプの応答本文を文書化するにはどうすればよいですか？

Answer 1

オブジェクトの配列は次のように定義される：あなたの例で

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

、応答は、プロパティbalanceDisplaySettings持つオブジェクトが含まれており、このプロパティは、オブジェクトの配列を含んでいます。これは以下のように定義することができ、次のとおりです。スキーマは、あなたがどこにも実際の値（"Balance"、"AvailableBalance"、など）を指定する必要はありませんつまり、応答構造を定義すること

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 

注意を。あなたが闊歩UIの例としてあなたのポスト（2つのオブジェクトの配列）からの例を表示したい場合は、このようにそれを追加することができます。

   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