Swagger UI est une page web qui montre comment fonctionne une API et permet de l'essayer. Un développeur décrit l'API dans un fichier standard, et Swagger UI lit ce fichier pour afficher chaque action disponible sous forme de liste cliquable. Vous ouvrez une action, vous remplissez quelques champs, vous cliquez sur un bouton et vous voyez la vraie réponse renvoyée par le serveur.

Pas besoin d'être développeur pour en tirer parti. Si vous confiez une application sur mesure à une agence, si vous reliez votre boutique en ligne à un entrepôt ou si vous évaluez un éditeur de logiciel, la page Swagger UI est souvent la preuve la plus claire de ce que le système sait vraiment faire. Elle transforme une promesse comme « nous avons une API » en une liste que vous pouvez lire, partager et vérifier.

Qu'est-ce que Swagger UI ?

Swagger UI est un outil open source, écrit en JavaScript, qui génère une documentation interactive à partir d'un fichier OpenAPI. Ce fichier, en YAML ou en JSON, décrit une API : ses endpoints (les adresses que l'on peut appeler), les méthodes (GET pour lire, POST pour créer, etc.), les paramètres acceptés, la forme des données renvoyées, les codes d'erreur et la manière de s'authentifier.

Swagger UI ne crée pas l'API et n'écrit pas la description. C'est une visionneuse doublée d'une console de test. Le même fichier OpenAPI peut alimenter d'autres outils : générateurs de code, suites de tests, serveurs de simulation ou autres visionneuses au design différent.

Les noms prêtent à confusion, alors voici l'histoire en bref. « Swagger » était le nom d'origine de la spécification, créée en 2011. En 2016, elle a été confiée à un groupement ouvert d'entreprises et rebaptisée OpenAPI Specification. Les outils, eux, ont gardé la marque Swagger : Swagger UI pour la documentation interactive, Swagger Editor pour écrire le fichier, Swagger Codegen pour générer du code. Aujourd'hui, OpenAPI désigne donc le format, et Swagger UI l'une des façons les plus répandues de l'afficher.

Ce que Swagger UI n'est pas :

  • Ce n'est pas un portail développeur complet avec guides, tutoriels et facturation, même s'il s'y trouve souvent intégré.
  • Ce n'est pas une preuve que l'API fonctionne bien. Il montre ce que la description affirme, et cette description peut être périmée.
  • En théorie, il n'est pas réservé aux API REST, mais en pratique il est conçu pour les API HTTP décrites en OpenAPI, pas pour GraphQL.

Pourquoi c'est important

Pour une fondatrice ou un vendeur, Swagger UI compte parce qu'il rend visible un travail qui ne l'est pas. Sans lui, une API reste une boîte noire que vous payez sans pouvoir l'inspecter.

Imaginons une marque qui paie un freelance 6 000 € pour développer un petit backend qui synchronise les commandes entre sa boutique et un entrepôt. Le devis mentionne « API documentée ». Sans référence partagée et lisible, le développeur suivant passe deux ou trois jours à décortiquer le code avant de pouvoir modifier quoi que ce soit. À 70 € de l'heure, trois jours de découverte représentent près de 1 700 € perdus à chaque passation. Avec une page Swagger UI à jour, un nouveau développeur comprend les endpoints en une heure et les teste l'après-midi même.

Il raccourcit aussi la question « votre outil sait-il faire X ? ». Quand vous évaluez un éditeur, vous ouvrez sa référence d'API publique, vous cherchez « orders » ou « inventory », et vous voyez en quelques minutes si vous pouvez lire le stock, créer des codes promo ou exporter vos clients. C'est plus rapide et plus fiable qu'un rendez-vous commercial.

Enfin, Swagger UI allège le support de l'entreprise qui publie l'API. Les partenaires testent eux-mêmes leurs appels au lieu d'envoyer des e-mails.

Comment ça marche

Du fichier de description à la page interactive, le chemin est le suivant :

  • Quelqu'un décrit l'API. Un développeur écrit le fichier OpenAPI à la main, ou le génère à partir d'annotations dans le code du backend.
  • Le fichier est publié. Il est mis en ligne à une URL, par exemple à côté de l'API elle-même.
  • Swagger UI charge le fichier. Une page web statique contenant le script Swagger UI pointe vers cette URL. À l'ouverture, le script télécharge le fichier et l'analyse.
  • Les endpoints sont classés et listés. Chaque opération apparaît sous une étiquette, avec sa méthode, son chemin et son résumé. Un clic révèle les paramètres, le schéma des données envoyées, des exemples et les réponses possibles.
  • Vous vous authentifiez. Un bouton « Authorize » permet de saisir une clé d'API ou de passer par une connexion OAuth, pour que les appels de test portent des identifiants valides.
  • Vous essayez. Le bouton « Try it out » transforme les champs en formulaire. Sur « Execute », votre navigateur envoie la vraie requête HTTP et affiche le code de réponse, les en-têtes et le contenu, ainsi que la commande équivalente en ligne de commande.
  • La page reste à jour si le fichier l'est. Quand les développeurs modifient le fichier OpenAPI, la page change au chargement suivant. S'ils oublient, la page ment.

Repères et exemples

Quelques repères pour juger ce que vous voyez :

  • Couverture. Chaque endpoint réellement proposé doit apparaître. Un éditeur dont la présentation commerciale annonce 40 fonctionnalités mais dont le Swagger UI montre 8 endpoints vous envoie un signal.
  • Descriptions. Une bonne page a un résumé d'une ligne sur chaque opération et un exemple pour chaque requête. Des descriptions vides signifient en général que le fichier a été généré automatiquement puis jamais relu.
  • Erreurs documentées. Une API sérieuse liste ses réponses d'erreur, au minimum 400, 401, 403, 404 et 429.
  • Fraîcheur. Regardez le numéro de version en haut de la page et comparez-le au journal des modifications. Un écart de plusieurs versions est mauvais signe.

Des situations typiques :

  • Une marque confie une application de fidélité à une agence. L'agence partage un lien Swagger UI au dixième jour, et le product owner de la marque confronte chaque endpoint aux critères d'acceptation.
  • Un fondateur qui construit un MVP ouvre Swagger UI pendant ses démonstrations pour prouver aux investisseurs que le backend existe vraiment.
  • Une gérante de boutique qui compare des outils d'expédition consulte la référence d'API de chacun pour savoir lesquels acceptent l'envoi automatique des commandes.

Erreurs fréquentes

  • Laisser une console de test ouverte en production avec de vraies clés. Une page publique qui permet à n'importe qui d'exécuter des appels sur des données réelles est un risque de sécurité. Restreignez-la ou reliez-la à un environnement de test.
  • Laisser le fichier dériver. Une documentation écrite une fois puis oubliée est pire que pas de documentation, parce qu'on lui fait confiance.
  • Prendre « on a du Swagger » pour un gage de qualité. La page montre ce qui existe sur le papier. Demandez un test en direct devant vous.
  • Laisser visibles des endpoints internes. Les fichiers générés automatiquement incluent parfois des routes d'administration qui ne devraient jamais être publiques.

Bonnes pratiques

  • Générez le fichier depuis le code. Quand la description est produite à partir des sources, il devient bien plus difficile qu'elle prenne du retard.
  • Exigez résumés et exemples. Demandez à votre développeur une phrase en langage clair et un exemple réaliste pour chaque endpoint.
  • Prévoyez un bac à sable. Reliez « Try it out » à un environnement de test rempli de fausses données, pour que personne ne touche aux vraies commandes par erreur.
  • Protégez la page si besoin. Une API interne peut se cacher derrière une connexion. Une API publique doit masquer les opérations d'administration.
  • Inscrivez-le au contrat. Quand vous faites appel à un prestataire, listez « fichier OpenAPI à jour avec Swagger UI » parmi les livrables, vérifiés à chaque étape.
  • Versionnez. Affichez la version de l'API sur la page et tenez un court journal des modifications à côté.

Dans Roctify

Roctify ne publie pas d'API publique, il n'y a donc pas de page Swagger UI Roctify à explorer. La plateforme est un SaaS no-code : vous gérez produits, variantes, stock, commandes, clients, codes promo et paiements depuis le tableau de bord, et votre page lien en bio comme votre vitrine lisent le même catalogue. Roctify héberge la boutique, la maintient à jour et sert chaque page en HTTPS avec un certificat SSL gratuit, vous n'avez donc aucun backend à documenter.

Swagger UI devient utile quand vous reliez Roctify à d'autres systèmes ou que vous prévoyez des développements autour. Si vous évaluez un outil d'entrepôt, de comptabilité ou un ERP, sa page Swagger UI vous dit ce qu'il sait échanger. Si vous avez besoin d'intégrations au-delà des fonctionnalités intégrées, elles se discutent dans l'offre Enterprise.

FAQ

Swagger UI et OpenAPI, c'est pareil ?

Non. OpenAPI est le format standard qui décrit une API. Swagger UI est un outil qui lit un fichier OpenAPI et l'affiche sous forme de page interactive. D'autres visionneuses peuvent afficher un fichier OpenAPI, mais Swagger UI a toujours besoin d'un tel fichier.

Swagger UI est-il gratuit ?

Oui. Swagger UI est open source sous licence Apache 2.0 et peut être auto-hébergé sans frais. Certaines entreprises paient des plateformes hébergées de conception et de documentation qui l'intègrent, mais l'outil lui-même est gratuit.

Peut-on utiliser Swagger UI sans savoir coder ?

Vous pouvez lire et tester une page existante sans code, à condition d'avoir des identifiants d'accès. Créer le fichier OpenAPI et héberger la page relève du travail d'un développeur, en général une petite partie d'un projet d'API s'il est prévu dès le départ.