L’élément central de Swagger est, en fonction de son champ d’application, un fichier au format JSONP ou YAML. L’interface utilisateur, qui permet de représenter très facilement la documentation, fonctionne avec HTML et JavaScript. En principe, Swagger présente un format indépendant de tout langage informatique et lisible par une machine. À partir de l’interface utilisateur, on peut non seulement administrer la documentation, mais aussi s’en servir pour que Swagger effectue, par exemple, des tests ad hoc.
Swagger présente un avantage évident avec son mode développement, assuré par une bibliothèque centrale, Swagger Core. L’interface utilisateur s’appelle Swagger UI, le générateur de code Swagger Codegen, et il existe aussi un Swagger Editor.
Mais la grande force de Swagger, tout comme de nombreuses autres solutions open source, réside dans l’écosystème complet de GitHub. Là, les développeurs trouveront des générateurs de code pour presque tous les langages de programmation. Swagger documente chaque interface avec toutes les informations.
Le fichier de documentation commence par renseigner la version de la spécification utilisée, suivie de quelques informations générales sur l’API, clairement classées dans la catégorie info. Swagger distingue également l’hôte, le chemin et le schéma d’URL et les mentionne séparément. Ensuite seulement, on retrouve le type de média pour l’ensemble de l’API. Cette préparation s’apparente à un système complexe de fiches bristol.
Une fois cette catégorisation achevée, on représente les contenus : chemins, opérateurs et paramètres sont préparés avec leurs descriptions correspondantes. Les types de données sont administrés à part, dans une section dédiée. Swagger UI permet de représenter l’ensemble non seulement au format texte, mais aussi par une visualisation graphique. Une propriété surtout avantageuse lorsque les requêtes tests directes doivent être envoyées depuis le navigateur. Ce mélange entre documentation parfaite doublée de la possibilité de résoudre, en parallèle, des requêtes API directes, donne toute sa valeur à Swagger.