Accès et mise à jour de la documentation d'une API importée

Quand vous importez une spécification, Restorm ne crée pas seulement des requêtes : il conserve la documentation de l’API — descriptions, modèles, schémas de sécurité, exemples, énumérations — et l’attache au dossier de variables créé par l’import.

Accéder à la documentation

L’onglet Docs du dossier de variables

C’est la vue principale. Ouvrez le dossier de variables issu de l’import : sa barre de sous-onglets porte un onglet Docs, à côté de Environnements, Variables personnalisées et Notes.

L’onglet n’apparaît que si le dossier vient d’un import — un dossier de variables que vous avez créé à la main n’a pas de documentation à afficher.

Les autres accès

Depuis	Ce que vous obtenez
L’onglet Docs d’une requête	La documentation de cette seule opération — sans sommaire ni bloc d’informations générales. Il n’apparaît que si l’opération est retrouvée dans la spécification
L’onglet Docs d’un dossier simple	La documentation restreinte aux opérations que ce dossier contient
Le sous-onglet d’accueil du dossier de variables	La carte Voir la documentation — « Parcourez la documentation de l’API, les modèles et les endpoints »
L’écran d’accueil (carte API)	Le lien rapide Documentation
Le moteur de recherche de la barre de titre	Un aperçu de la documentation au survol d’un résultat

Ce que contient la vue

De haut en bas :

• le titre de l’API et sa description ;
• un bloc d’informations : Version, Source format (avec un lien vers l’URL source), Server (schémas, hôte, chemin de base), Contact, License, Terms of service, External docs ;
• une section par étiquette, avec sa description ;
• un bloc par opération : méthode et URL, résumé, pastille de groupe, badge deprecated le cas échéant, section Security (type de schéma, flux OAuth 2, portées), et un Example payload repliable ;
• les tableaux Parameters et Responses (les codes de statut sont colorés) ;
• Models — un graphe interactif des schémas, navigable et zoomable ;
• Polymorphism — les compositions oneOf / anyOf / allOf ;
• Enums — les énumérations, fusionnées avec celles du dossier.

Note

Les intitulés de ces sections (Models, Enums, Parameters, Responses, Security, Example payload) sont affichés en anglais dans toutes les langues de l’application. Ils sont repris tels quels ici pour que vous les retrouviez à l’écran.

Créer une requête depuis la documentation

Chaque bloc d’opération porte un bouton + Add qui crée une requête préconfigurée pour cette opération. C’est le chemin le plus court quand un import a été partiel, ou quand une opération vient d’apparaître dans la spécification.

Naviguer et chercher

Un sommaire est ancré à droite — sections Overview, Operations, Models, Enums — repliable et redimensionnable. Cliquer un modèle fait défiler jusqu’au graphe et y centre le nœud correspondant.

Raccourci	Effet
Ctrl+F / Cmd+F	Ouvre la recherche dans la documentation
F3 / Entrée	Correspondance suivante
Shift+F3 / Shift+Entrée	Correspondance précédente
Échap	Ferme la recherche

Un compteur indique la position dans les résultats.

Mettre à jour la documentation

Une spécification évolue. Restorm sait aller rechercher la source et appliquer le delta — documentation et requêtes — sans écraser votre travail.

Uniquement pour les imports par URL

La resynchronisation n’est disponible que si le dossier a été importé depuis une URL. Un import depuis un fichier ou par collage n’enregistre pas de source, et le bouton d’actualisation n’apparaît pas : le sous-onglet d’accueil affiche alors « Ce dossier n’a pas été créé depuis une source importable. »

Cette URL n’est pas modifiable après coup dans l’interface. Pour changer de source, refaites un import.

Où se trouve le bouton

Deux entrées, équivalentes :

1. le sous-onglet d’accueil du dossier de variables, section Mises à jour de la spec — elle affiche l’URL, le Dernier import et la Dernière vérification, et porte le bouton Actualiser ;
2. le clic droit sur le dossier dans l’arbre latéral → Actualiser.

Il n’y a pas de vérification automatique

Restorm ne surveille pas vos spécifications en arrière-plan et ne vous préviendra pas qu’une nouvelle version est disponible. La vérification est toujours déclenchée par vous.

Ce qui se passe

1. Une fenêtre « Actualisation de la spec… » apparaît pendant la récupération. Les {{variables}} de l’URL et des en-têtes sont résolues, et la route d’authentification attachée est jouée au préalable.
2. Restorm compare une empreinte de la source récupérée à celle enregistrée au dernier import.
3. Rien n’a changé → « La spec de l’API est à jour. », et c’est terminé.
4. Quelque chose a changé (ou la récupération a échoué) → l’assistant de resynchronisation s’ouvre.

L’assistant

• L’URL source est affichée en lecture seule.
• Une pastille permet d’attacher, modifier ou détacher une route d’authentification, et un sous-menu Custom headers d’ajouter des en-têtes fixes rejoués à chaque actualisation.
• Deux onglets de prévisualisation :
  • Routes — l’arbre des opérations trouvées dans la nouvelle version, avec filtre et sélection. Les opérations déjà présentes dans votre dossier sont verrouillées et toujours cochées ; vous choisissez seulement lesquelles des nouvelles ajouter ;
  • Documentation — la documentation de la nouvelle version, en lecture seule, avant de valider.
• Le bouton de validation affiche le nombre de nouvelles opérations sélectionnées, par exemple Apply update (3).

Note

L’assistant est aujourd’hui affiché en anglais quelle que soit la langue de l’application (« Refresh from source », « Apply update », onglets « Routes » et « Documentation »). Les intitulés anglais sont donc repris ici tels quels.

Ce qui est modifié, et ce qui ne l’est pas

C’est le point important : la spécification fait autorité sur ce qu’elle décrit, vous faites autorité sur le reste.

Élément	Comportement
Nom d’une requête	Jamais modifié
Méthode et URL	Jamais modifiées
Paramètres, en-têtes et paramètres de chemin existants	Conservés tels quels — valeur, description, activation
Paramètres ajoutés par la spécification	Ajoutés, avec la valeur par défaut de la spécification ou vides
Paramètres retirés de la spécification	Conservés sur la requête
Opération nouvelle	Ajoutée à l’endroit où un import neuf l’aurait placée (dossier d’étiquette compris)
Opération marquée dépréciée par la spécification	Signalée ; elle apparaît estompée dans l’arbre
Opération disparue de la spécification	Signalée comme retirée ; elle apparaît barrée dans l’arbre, reste exécutable et n’est jamais supprimée
Documentation d’API et énumérations	Remplacées intégralement par la nouvelle version — c’est ce qui rafraîchit l’onglet Docs

Rien n’est jamais supprimé de votre arbre : une opération qui disparaît de la source est marquée, pas effacée.

Si la source demande une authentification

Une réponse 401 ou 403 ouvre l’assistant avec le message d’erreur affiché tel quel (par exemple HTTP 401: Unauthorized). Attachez une route d’authentification ou ajoutez des en-têtes fixes, et la prévisualisation est relancée.

Formats resynchronisables

Douze formats disposent de la resynchronisation : Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC et Smithy.

Pour tous les autres, un nouvel import crée un nouvel arbre. La liste complète est dans Mettre à jour depuis la source.