Schémas OpenAPI
Si un document OpenAPI 3.1 ou plus récent contient des schémas OpenAPI au sein de son objet component/schemas (voir la capture d'écran de la vue Texte ci-dessous à gauche), ces schémas peuvent alors être consultés et modifiés dans la vue graphique Schéma de XMLSpy (capture d'écran ci-dessous à droite). Pour ce faire, il suffit de passer de la vue Texte ou de la vue Grille du document OpenAPI à la vue Schéma. Ce faisant, les schémas contenus dans l’objet component/schemas s’afficheront dans la grille d'aperçu des définitions (capture d’écran ci-dessous à droite).
Pour afficher ou modifier l’un des schémas répertoriés, cliquez sur son icône dans la grille d’aperçu des définitions.
Les schémas sont également répertoriés dans l’aide à la saisie Aperçu de la vue Schéma (capture d’écran ci-dessous). Vous pouvez double-cliquer sur un schéma à cet endroit pour le modifier dans le Mode Design.
Les schémas peuvent être modifiés de la même manière que n’importe quel schéma JSON. Voir la section Schémas JSON pour plus d’informations.
Notez les points suivants :
•Les schémas définis au sein de l’objet component/schemas sont appelés schémas nommés.
•Seuls les schémas nommés peuvent être modifiés en tant que schémas dans la vue Schéma. Si un schéma est défini à un autre emplacement dans le document OpenAPI, c’est-à-dire en dehors de l’objet component/schemas, il ne peut pas être modifié dans la vue Schéma.
•Dans la vue Schéma, si vous ajoutez une nouvelle définition de schéma, celle-ci sera ajoutée en tant que nouveau schéma nommé à l’objet component/schemas.
Valider les objets OpenAPI en tant que structures JSON/YAML
Un objet OpenAPI sous la forme d’une structure JSON ou YAML peut être validé (dans la vue Texte ou la vue Grille) par rapport à un schéma JSON.
Il s’agit d’une validation JSON, et non d’une validation OpenAPI. Le document à valider doit être un objet JSON ou YAML qui ne commence pas par la clé « openapi » ou « swagger ». S’il commence par l’une de ces clés, le document est alors un document OpenAPI et sera validé par rapport à la spécification OpenAPI ; voir Modifier et valider des documents OpenAPI.
Pour attribuer un schéma JSON à un document contenant un objet OpenAPI dans une structure JSON ou YAML, procédez comme suit. (Notez que le fichier doit être au format .json ou .yaml et ne doit pas avoir la clé openapi ou swagger comme clé racine.)
1.Accédez à la fenêtre Informations (capture d'écran ci-dessous) du fichier JSON ou YAML qui n'est pas un fichier OpenAPI.
2.Cliquez sur Validation par rapport au schéma | Sélectionner un schéma JSON.
3.Sélectionnez le fichier de schéma JSON souhaité. Le dialogue Sélectionner un schéma s’affiche (captures d’écran ci-dessous), dans lequel apparaissent les schémas nommés du fichier de schéma sélectionné. Si vous sélectionnez un fichier OpenAPI, ses schémas nommés sont répertoriés et vous pouvez en sélectionner un (capture d’écran ci-dessous à gauche). Si vous sélectionnez un fichier de schéma JSON, vous pouvez choisir, en plus des schémas nommés, le schéma racine (voir capture d’écran ci-dessous à droite).
4.Cliquez sur OK pour terminer l’affectation. L’affectation s’affichera dans la fenêtre Info (voir la capture d’écran à l’étape 1).
Vous pouvez désormais valider le document JSON ou YAML d’instance par rapport à la définition de schéma nommé ou au schéma JSON qui lui a été affecté. Pour ce faire, utilisez la commande XML | Valider XML (F8).
Générer un exemple
Vous pouvez générer une structure JSON ou YAML d’exemple à partir d’une définition de schéma nommé. La structure sera créée dans un fichier portant l’extension correspondante (.json ou .yaml).
Pour ce faire, procédez comme suit :
1.Sélectionnez la commande DTD/Schéma | Générer fichier échantillon XML/JSON/YAML.
2.Dans le dialogue Sélectionner schéma qui s’affiche (voir les captures d’écran ci-dessus), sélectionnez la définition de schéma nommé pour laquelle vous souhaitez créer le fichier d’exemple, puis cliquez sur OK.
3.Dans le dialogue Générer fichier échantillon JSON/YAML qui s’affiche alors, sélectionnez le type de fichier souhaité (JSON ou YAML), définissez les options appropriées, puis cliquez sur OK.
Le fichier d'exemple généré aura automatiquement pour schéma associé la définition de schéma nommée que vous avez sélectionnée, et vous pourrez immédiatement valider ce fichier d'exemple.
Note : un fichier d'exemple peut également être créé lorsque vous créez un nouveau fichier JSON ou YAML (commande de menu Fichier | Nouveau) et que vous choisissez, à ce moment-là, d'associer un schéma JSON au nouveau fichier.