Documentation API & Swagger Explorer
Documentation API & Swagger Explorer
Consultez et diagnostiquez rapidement les routes et opérations exposées
Accédez à la documentation Swagger pour explorer les routes/opérations, rechercher une operationId et gérer la mise en cache pour des accès plus rapides.
La Documentation API & Swagger Explorer vous permet de charger une spécification Swagger (swagger.yaml) depuis une URL, d’explorer les routes et d’obtenir le détail de chaque opération. C’est utile pour intégrer des systèmes, vérifier des comportements ou diagnostiquer des erreurs sans deviner les noms de routes.
Depuis une récente mise à jour, l’accès à l’Explorer Swagger peut être restreint par une logique côté serveur (implémentée dans AppServiceProvider) et la spécification swagger.yaml a été modifiée en conséquence. Certaines URLs ou environnements peuvent retourner une erreur d’autorisation (403) ou être inacessibles directement. Si votre requête est refusée, suivez la procédure décrite ci‑dessous pour demander l’accès ou obtenir une copie de la spec.
Principales capacités
Charger / importer la spec
Importer un swagger.yaml via une URL publique ou coller directement l’URL dans l’outil pour afficher instantanément la documentation et les routes. Remarque : si l’accès est restreint côté serveur, l’outil affichera un message d’autorisation — suivez la procédure de demande d’accès (voir FAQ et étapes ci‑dessous).
Rechercher par operationId
Trouver rapidement une opération précise en tapant son operationId : accès direct aux paramètres, réponses attendues et exemples.
Cache côté client
La documentation est mise en cache dans votre navigateur pour des temps de chargement plus rapides ; vous pouvez forcer un rafraîchissement si nécessaire.
Voir les détails d’une route
Consultez les paramètres, types, formats et descriptions associés à chaque opération pour préparer vos appels ou diagnostiquer un problème.
Télécharger / charger depuis URL
Sauvegardez ou rechargez la même URL facilement pour partager la spec avec l’équipe ou comparer différentes versions.
Performance & diagnostic
L’outil affiche clairement les erreurs de parsing et les problèmes réseau afin que vous sachiez si la spec est invalide ou si la connexion a échoué.
How to use it
Actions principales — pas à pas
Charger la documentation (URL ou import)
- Ouvrez l’outil “Documentation API / Swagger Explorer”.
- Dans le champ “URL” collez l’adresse publique du swagger.yaml ou utilisez le bouton “Importer”.
- Cliquez sur “Charger” ou “Télécharger”.
- Ce qui se passe : l’outil récupère le YAML, le parse et affiche la table des routes et opérations. Si le fichier est valide, vous verrez la liste organisée par chemins et méthodes.
- En cas d’erreur : l’interface affiche un message clair (ex. : erreur de parsing, fichier introuvable, ou problème de connexion).
- Si le serveur refuse l’accès (code 403, redirection vers une page d’authentification ou message d’autorisation), l’Explorer est probablement restreint côté serveur. Pour obtenir l’accès, contactez l’équipe API en précisant l’URL demandée, votre adresse IP publique, le nom de votre projet/integration et le motif (ex. test, intégration continue, diagnostic). L’équipe vous indiquera la procédure (ou fournira une copie autorisée de la spec).
Rechercher une opération par operationId
- Dans la barre de recherche en haut, saisissez exactement l’operationId (copier/coller recommandé).
- Appuyez sur Entrée ou cliquez sur l’icône de recherche.
- Ce qui se passe : l’outil filtre la liste et ouvre le panneau de détails pour l’opération trouvée (paramètres, format attendu, réponses d’exemple).
- Astuce pratique : si vous ne trouvez rien, essayez une partie de l’operationId ou vérifiez les espaces/caractères spéciaux.
Inspecter le détail d’une route
- Après la recherche ou en cliquant sur une route dans la liste, regardez le panneau à droite :
- paramètres attendus (nom, emplacement, type, requis)
- exemples de réponse
- descriptions et codes HTTP possibles
- Ce qui se passe : vous pouvez copier les informations nécessaires pour l’intégration ou transmettre un diagnostic précis à un collègue.
Mettre à jour le cache / forcer un rafraîchissement
- Si vous suspectez que la spec a changé côté serveur, utilisez le bouton “Rafraîchir” ou activez l’option “fresh” avant de charger.
- Cliquez sur “Rafraîchir” → l’outil ignore la version mise en cache et recharge la spec depuis l’URL.
- Ce qui se passe : la cache locale est mise à jour et la nouvelle version est affichée. Si la recharge échoue, un message indique la raison (connexion, parsing…).
Télécharger ou partager la spec
- Utilisez l’option “Télécharger” pour obtenir une copie locale de la spec affichée.
- Pour partager, copiez l’URL utilisée ou utilisez la fonction “Partager” de l’outil (si disponible).
- Ce qui se passe : vos collègues peuvent recharger exactement la même version et reproduire vos vérifications.
Bonnes pratiques
- Conservez l’URL du swagger.yaml dans vos notes d’équipe pour gagner du temps.
- Copiez-collez l’operationId depuis votre code ou votre document de spécification pour éviter les fautes de frappe.
- Quand vous diagnostiquez un problème, capturez la version chargée (date/heure) et le message d’erreur affiché pour le transmettre.
Limites et règles importantes
- La documentation est mise en cache côté client : si la spec côté serveur a changé, pensez à forcer le rafraîchissement (option “fresh”) pour voir la version la plus récente.
- Le parsing du YAML peut échouer si le fichier est invalide : l’interface affichera une erreur de parsing — corrigez la spec côté source ou demandez à la personne responsable.
- Si la récupération échoue, vérifiez votre connexion ou que l’URL est accessible depuis votre réseau (les ressources protégées peuvent bloquer le chargement).
- L’accès à l’Explorer peut aussi être restreint côté serveur par une politique (AppServiceProvider) : dans ce cas, vous devrez demander explicitement l’autorisation à l’équipe API (voir la FAQ ci‑dessous).
- Les specs très volumineuses peuvent ralentir l’affichage et la recherche : soyez patient ou travaillez avec une version allégée si possible.
FAQ
Frequently Asked Questions
Besoin d’aide pour une route spécifique ?
Si vous rencontrez un cas bloquant, copiez l’operationId et le message d’erreur et partagez-les avec l’équipe pour une résolution rapide. Si l’accès à l’Explorer est restreint, demandez l’autorisation en joignant l’URL, votre IP publique et le motif de la demande.