Swagger UI: plusieurs objets anonymes dans le tableau

Question

J'écris une documentation Swagger pour une API, et un point de terminaison renvoie de nombreux objets et paramètres imbriqués.

Toutefois, il existe un tableau renvoyé qui ne renvoie pas de paramètres normaux. Au lieu de cela, il renvoie deux objets anonymes qui contiennent les paramètres.

"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 

Regarder la documentation de fanfaronnades pour la description du corps de demande, il n'y a apparemment aucun moyen de manipuler des objets sans nom. Comment puis-je (en utilisant YAML) documenter ce type de corps de réponse dans Swagger-UI?

Answer 1

Un tableau d'objets est défini comme suit:

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

Dans votre exemple, la réponse contient un objet avec la propriété balanceDisplaySettings, et cette propriété contient un tableau d'objets. Cela peut défini comme suit:

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 

Notez que le schéma définit la réponse la structure, ce qui signifie que vous n'avez pas besoin de spécifier les valeurs réelles ("Balance", "AvailableBalance", etc.) partout. Cependant, si vous voulez afficher l'exemple de votre message (tableau avec 2 objets) comme un exemple dans l'interface utilisateur Swagger, vous pouvez l'ajouter comme ceci:

   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 

Enfin, vous pouvez diviser la ligne schéma imbriqué pour rendre la spécification plus modulaire.

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