Création d'un fichier de JSON de spécification Swagger
Si vous devez créer un fichier de JSON de spécification Swagger, vous pouvez commencer par le modèle fourni ici.
About this task
Le modèle inclut des éléments passe-partout :
| Nom de zone | Type | |
|---|---|---|
| openapi | chaîne | REQUIS. Cette chaîne doit être le numéro de version sémantique de la version de spécification OpenAPI qu'utilise le document OpenAPI. Cette zone doit être utilisée par les spécifications d'outils et les clients pour interpréter le document OpenAPI. Elle n'est pas liée à la chaîne d'API. |
| info | Objet Info | REQUIS. Fournit des métadonnées sur l'API. Les métadonnées PEUVENT être utilisées par les outils selon les besoins. |
| serveurs | Objet Serveur | Matrice d'objets serveur qui fournit des informations de connectivité à un serveur cible. Si la propriété n'est pas fournie ou s'il s'agit d'une matrice vide, la valeur par défaut est un objet serveur avec une valeur d'URL de /. |
| paths | Objet Chemins d'accès | REQUIS. Chemins et opérations disponibles pour l'API. |
| composants | Objet Composants | Elément qui permet de contenir différents schémas pour la spécification. |
| sécurité | Objet Exigences de sécurité | Déclaration des mécanismes de sécurité qui peuvent être utilisés dans l'API. La liste des valeurs inclut d'autres objets d'exigence de sécurité qui peuvent être utilisés. Un seul des objets d'exigence de sécurité doit être satisfait pour autoriser une requête. Les opérations individuelles peuvent écraser cette définition. Pour rendre la sécurité facultative, une exigence de sécurité vide peut être incluse dans la matrice. |
| tags | Objet Balise | Liste des balises utilisées par les spécifications avec des métadonnées supplémentaires. L'ordre des balises peut être utilisé pour refléter leur ordre par les outils d'analyse. Toutes les balises utilisées par l'objet opération ne doivent pas être déclarées. Les balises qui ne sont pas déclarées peuvent être organisées de manière aléatoire ou en fonction de la logique de l'outil. Chaque nom de balise de la liste doit être unique. |
| externalDocs | Objet de documentation externe | Documentation externe supplémentaire. |
Vous devez déterminer plusieurs choses avant de créer un fichier JSON.
- Quels paramètres allez-vous utiliser (décrit ici : http://swagger.io/specification/#parameterObject)?
- Que produit la méthode que vous créez ? Dressez une liste des types de données qui peuvent être renvoyés depuis l'opération.
- Que consomme la méthode ? Dressez une liste des types de données consommés par l'opération.
- Quelles sont les réponses valides (décrit ici : http://swagger.io/specification/#responseObject)?
Pour ajouter un nouveau schéma, ajoutez un objet de schéma à l'objet composants.
Principaux points à garder à l'esprit
- Le nom de schéma.
- Structure de l'objet de schéma. Pour obtenir des conseils, voir la documentation Objet de schéma dans la spécification Swagger. Notez qu'un objet de schéma peut en contenir un autre, par référence. Par exemple, voir la zone adresse. Considérez ce modèle simple comme un autre exemple d'objet de schéma.
Ajout d'en-têtes aux réponses
Les en-têtes renvoyés avec des réponses peuvent être décrits en ajoutant une propriété d'en-tête pour chaque objet de réponse.
Par exemple, en ajoutant un en-tête nommé Emplacement à la réponse d'une requête POST dans laquelle une ressource est créée :
Pour plus de détails, voir la spécification OpenAPI.
Procedure
- Accédez à l'éditeur Swagger.
- Sélectionnez le menu déroulant Insérer et sélectionnez Ajouter des éléments de chemin d'accès pour ajouter le chemin.
- Ajoutez une opération en sélectionnant Ajouter une opération.
- Ajoutez une réponse en sélectionnant Ajouter un exemple de réponse.