# Modifier une spec (/fr/docs/specs/editing)

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 [#the-visual-editor]

<Shot id="specs-visual-endpoint" alt="L’éditeur visuel avec l’endpoint GET /products de la spec Alpenglow ouvert : méthode et chemin, résumé, description, ID d’opération et tags, puis les sections Paramètres, Corps de la requête et Réponses" />

Les champs de l’éditeur visuel modifient le document quand vous avez fini de les modifier : appuyez sur <kbd>↩</kbd> ou
passez à un autre champ. Les champs de description acceptent le Markdown, et <kbd>↩</kbd> 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 [#adding-an-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 [#adding-a-schema]

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 [#swagger-20]

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 [#the-code-editor]

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 <kbd>⌘</kbd>-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 [#saving]

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 [#undo]

**Édition › Annuler** (<kbd>⌘</kbd><kbd>Z</kbd>) annule les modifications dans l’un ou l’autre éditeur, et **Édition ›
Rétablir** (<kbd>⇧</kbd><kbd>⌘</kbd><kbd>Z</kbd>) 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 [#with-an-agent]

Les [agents](/docs/ai/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**.