EcholotModifier une spec
Concevez un document OpenAPI dans l’éditeur visuel ou en YAML, avec validation à la saisie, enregistrement et annulation.
Vous modifiez une spec de deux façons, et vous passez de l’une à l’autre à tout moment avec Éditeur dans l’en-tête de page : Visuel pour des cartes et des champs, Code pour le YAML ou le JSON lui-même. Les deux modifient le même texte. C’est le texte qu’Echolot conserve : une modification visuelle ne change que les lignes de la partie modifiée ; vos commentaires, votre ordre et votre mise en forme restent donc, et un diff Git montre exactement ce qui a changé.
Pour créer une spec, choisissez + › Nouvelle spec dans l’en-tête Specs de la barre latérale. Echolot écrit un
document OpenAPI 3.1 intitulé New API dans le dossier specs et l’ouvre dans l’éditeur visuel.
L’éditeur visuel
Les champs de l’éditeur visuel modifient le document quand vous avez fini de les modifier : appuyez sur ↩ ou passez à un autre champ. Les champs de description acceptent le Markdown, et ↩ y commence une nouvelle ligne ; le bouton à côté de l’un d’eux affiche la description telle qu’elle se lira.
La page comporte ces cartes :
| Carte | Ce que vous modifiez |
|---|---|
| Vue d’ensemble | Le Titre, la Version et la Description de l’API. |
| Serveurs | Les URL et les descriptions des serveurs. Ajouter un serveur en ajoute un ; le − en retire un. Sans serveurs, les requêtes créées à partir de la spec commencent par {{baseUrl}}, que vous définissez vous-même. |
| Contact et licence | Afficher ouvre le nom, l’e-mail et l’URL du contact, la licence et son URL, et les conditions d’utilisation. |
| Endpoints | Toutes les opérations. Grouper par les liste par Chemins ou par Tags (celles sans tag sous Sans tag). Cliquez sur l’une d’elles pour l’ouvrir. |
| Schémas | Les schémas réutilisables, auxquels les corps et les réponses peuvent faire référence par leur nom. Cliquez sur l’un d’eux pour l’ouvrir. |
Ajouter un endpoint
Cliquez sur Ajouter un endpoint dans la carte Endpoints. Dans la feuille Nouvel endpoint, choisissez la
méthode, saisissez le chemin (par exemple /products/{sku}) et, facultativement, un résumé et un tag, puis cliquez sur
Ajouter un endpoint. Echolot définit pour vous les paramètres du chemin et ajoute un corps et une réponse de succès
pour démarrer. Une méthode et un chemin qui existent déjà sont refusés.
Un endpoint ouvert comporte :
| Partie | Ce que vous modifiez |
|---|---|
| Endpoint | La méthode et le chemin. Les changer déplace l’opération. |
| Résumé, Description | Un nom court, par exemple List products, et ce qu’elle fait, exige et renvoie. |
| ID de l’opération, Tags | L’ID qu’utilisent les générateurs de code, et des tags séparés par des virgules. |
| Obsolète | Marque l’opération comme obsolète. |
| Paramètres | Le nom de chaque paramètre, où il va (Emplacement : path, query, header ou cookie), son type, Obligatoire et sa description. Ajouter un paramètre en ajoute un. Quand le chemin nomme un paramètre qui n’est pas défini, un bouton comme Ajouter {sku} le définit. Les paramètres marqués TOUT LE CHEMIN sont définis pour toutes les méthodes du chemin. |
| Corps de la requête | Ajouter un corps ajoute un corps JSON ; chaque type de média a un schéma et le corps peut être Obligatoire. Supprimer le corps le retire. |
| Réponses | Une ligne par code d’état, avec sa description et, après Ajouter un corps, ses types de média et ses schémas. Ajouter une réponse ajoute le prochain code courant non encore utilisé (200, 201, 204, 400, 401, 403, 404, 409, 422, 500, puis default). Modifiez le code pour le changer. Une opération a besoin d’au moins une réponse. |
Le type d’un paramètre, d’un corps ou d’une propriété est un menu : un schéma réutilisable, string, integer, number,
boolean ou object, un Tableau de l’un d’eux, ou Aucun. Un schéma que le menu ne peut pas exprimer est affiché
tel qu’il est écrit et conservé jusqu’à ce que vous choisissiez autre chose.
Au bas d’un endpoint ouvert se trouvent le premier problème que le linter y a trouvé (placez le pointeur dessus pour les voir tous) et trois boutons : Ouvrir la requête (quand une requête suit cette opération), Afficher dans le code et Supprimer l’endpoint.
Ajouter un schéma
Cliquez sur Ajouter un schéma dans la carte Schémas, donnez-lui un nom, par exemple Product, et cliquez sur
Ajouter. Un schéma ouvert a un Nom, une Description et ses Propriétés : chacune avec un nom, un type,
Obligatoire et une description. Ajouter une propriété en ajoute une.
Le schéma indique où il est utilisé (Utilisé à 3 endroits, ou Pas encore utilisé). Le renommer change toutes les références qui y renvoient. Supprimer le schéma demande d’abord confirmation quand le schéma est utilisé, puisque ces références ne pointeraient plus vers rien. Un schéma qui n’est pas un simple objet est décrit et modifié dans le code : Afficher dans le code vous y mène.
Swagger 2.0
Les documents Swagger 2.0 s’ouvrent dans l’éditeur visuel en lecture, et vous les modifiez dans Code. Echolot conçoit de l’OpenAPI 3.
L’éditeur de code
Passez Éditeur sur Code pour modifier directement le YAML ou le JSON. Le linter s’exécute pendant la saisie, après une courte pause : les erreurs et les avertissements sont soulignés sur leur ligne, et placer le pointeur sur l’un d’eux affiche le message.
Sur un $ref, placez le pointeur pour voir ce vers quoi il pointe ; faites ⌘-clic dessus pour y aller. Une
référence à un autre fichier ouvre ce fichier. Les fichiers auxquels une spec fait référence s’ouvrent toujours dans le
code.
Quand le texte ne s’analyse pas, l’éditeur visuel affiche L’éditeur visuel nécessite un document sans erreur de syntaxe., avec la ligne et l’erreur. Corriger dans le code va à cette ligne.
Enregistrer
Il n’y a rien à enregistrer à la main. Echolot écrit la spec peu après chaque changement, ainsi que lorsque vous passez à une autre spec, quittez la page ou fermez la fenêtre. Les mocks en cours d’exécution de la spec prennent en compte le changement.
Si le fichier ne peut pas être écrit (par exemple parce qu’il est devenu en lecture seule), Echolot affiche La spec n’a pas pu être enregistrée et garde vos modifications dans l’éditeur :
| Bouton | Ce qu’il fait |
|---|---|
| Réessayer | Tente à nouveau d’écrire le fichier. |
| Enregistrer une copie… | Écrit les modifications dans un fichier que vous choisissez. |
| Ignorer les modifications | Revient au fichier tel qu’il est sur le disque. |
| Continuer à modifier | Ferme le message. Les modifications restent, et la page reste sur cette spec jusqu’à ce qu’elles soient enregistrées. |
Annuler
Édition › Annuler (⌘Z) annule les modifications dans l’un ou l’autre éditeur, et Édition › Rétablir (⇧⌘Z) les rétablit. Chaque modification visuelle est une étape ; la saisie est une étape jusqu’à ce que vous fassiez une pause. Une annulation appartient à la spec qu’elle a modifiée : une fois que vous ouvrez un autre fichier, elle ne remonte pas dans le précédent.
Avec un agent
Les agents externes peuvent lire, écrire et valider les specs de l’espace de travail quand vous activez pour eux l’ensemble d’outils Specs dans Réglages › Agents.