web-dev-qa-db-fra.com

Comment puis-je décrire un modèle json complexe dans Swagger

J'essaie d'utiliser Swagger pour décrire les API web que je construis. Le problème est que je ne comprends pas comment décrire un objet json complexe?

Par exemple, comment décrire ces objets:

{
  name: "Jhon",
  address: [
    {
      type: "home",
      line1: "1st street"
    },
    {
       type: "office",
       line1: "2nd street"
    }
  ]
}
swaggerswagger-ui
30
Ido Ran

D'accord, donc sur la base des commentaires ci-dessus, vous voulez le schéma suivant:

{
  "definitions": {
    "user": {
      "type": "object",
      "required": [ "name" ],
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/address"
          }
        }
      }
    },
    "address": {
        "type": "object",
        "properties": {
            "type": {
                "type": "string",
                "enum": [ "home", "office" ]
            },
            "line1": {
                "type": "string"
            }
        }
    }
  }
}

J'ai fait quelques hypothèses pour rendre l'échantillon un peu plus compliqué, pour aider à l'avenir. Pour l'objet "utilisateur", j'ai déclaré que le champ "nom" est obligatoire. Si, par exemple, vous avez également besoin que l'adresse soit obligatoire, vous pouvez remplacer la définition par "obligatoire": ["nom", "adresse"].

Nous utilisons essentiellement un sous-ensemble de json-schema pour décrire les modèles. Bien sûr, tout le monde ne le sait pas, mais c'est assez simple à apprendre et à utiliser.

Pour le type d'adresse que vous pouvez voir, j'ai également défini la limite à deux options - à la maison ou au bureau. Vous pouvez ajouter n'importe quoi à cette liste, ou supprimer entièrement "l'énumération" pour supprimer cette contrainte.

Lorsque le "type" d'une propriété est "tableau", vous devez l'accompagner de "items" qui déclare le type interne du tableau. Dans ce cas, j'ai fait référence à une autre définition, mais cette définition aurait pu également être en ligne. Il est normalement plus facile de maintenir cette méthode, surtout si vous avez besoin de la définition "d'adresse" seule ou dans d'autres modèles.

Comme demandé, la version en ligne:

{
  "definitions": {
    "user": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "home",
                  "office"
                ]
              },
              "line1": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
41
Ron