4 options pour remplacer Swagger dans les API .NET 9

Mise en place d'un projet API standard

Tim commence par créer un projet API minimal dans Visual Studio, en choisissant le modèle standard ASP.NET Core Web API.

Il insiste sur le fait qu'il faut cocher la case pour ajouter la prise en charge d'OpenAPI, ce qui garantit que votre projet inclut la génération nécessaire de documents OpenAPI par le biais d'un point de terminaison de fichier JSON.

Une fois le projet lancé, Tim se rend à l'URL par défaut du document OpenAPI (par exemple, /swagger/v1/swagger.json) pour consulter les spécifications brutes de l'OpenAPI. Ce fichier contient des métadonnées structurées sur les points de terminaison de votre API, y compris les verbes pris en charge tels que GET, POST et DELETE.

Bien que fonctionnel, Tim note que l'affichage du document OpenAPI brut n'est pas convivial. Afin de fournir une meilleure interface de documentation basée sur le web, il présente ensuite quatre outils externes qui améliorent l'expérience du développeur et du consommateur.

Option 1 : Swagger UI - L'expérience familière

Swagger UI est toujours un outil très populaire, même s'il n'est plus inclus par défaut. Tim montre comment le ramener en utilisant le package NuGet requis dotnet : Swashbuckle.AspNetCore.SwaggerUI.

Après avoir configuré l'interface Swagger dans un nouveau projet, à 9:43, il configure l'intergiciel en utilisant une syntaxe simplifiée et définit l'URL de lancement à /swagger. Cette interface utilisateur fournit une interface de documentation API conviviale où les développeurs peuvent visualiser les points de terminaison, comprendre les paramètres des requêtes et les tester dans le navigateur.

Bien que Swagger UI soit désormais un outil externe, il prend toujours en charge les spécifications OpenAPI et reste l'un des meilleurs choix pour répondre aux besoins de documentation de base pendant le développement.

Option 2 : ReDoc - Documentation d'API propre et en lecture seule

Le deuxième outil de Tim est ReDoc, qui transforme votre document OpenAPI en un site HTML soigné, en lecture seule. Après avoir ajouté le paquet OpenAPI Swashbuckle.AspNetCore.ReDoc, il fait correspondre la documentation à /api/docs.

Contrairement à Swagger UI, ReDoc ne permet pas de tester les points d'extrémité. Cependant, elle se distingue en tant qu'interface de documentation basée sur le web, adaptée aux utilisateurs externes et aux clients. Si vous vous concentrez uniquement sur la définition d'API REST et l'affichage d'une documentation structurée, ReDoc est tout indiqué.

Il convient de noter que ReDoc génère automatiquement du contenu basé sur les spécifications OpenAPI fournies, couvrant les réponses attendues, les paramètres et les types de données. Cela correspond bien aux projets qui donnent la priorité à un support intégré optimisé pour la documentation plutôt qu'à l'interactivité.

Option 3 : NSwag - Documentation + Génération de code

Ensuite, Tim se plonge dans NSwag, un outil flexible et riche en fonctionnalités qui ne se contente pas de documenter les API : il peut également générer du code pour les clients dans différents langages comme C#, TypeScript, et bien plus encore. Après avoir installé le package NuGet NSwag.AspNetCore, il configure l'interface de type Swagger, en la mappant au même point de terminaison JSON.

Tim explique que NSwag prend en charge à la fois les spécifications Swagger et les normes OpenAPI, ce qui permet aux développeurs de choisir le format qu'ils préfèrent. Bien que l'interface utilisateur ressemble à Swagger, ce sont les bibliothèques d'outils externes et les fonctionnalités avancées (comme la création automatique de clients) qui font briller NSwag.

Il souligne que la capacité de NSwag à générer du code est utile pour réduire les efforts manuels lors de l'intégration avec des API, en particulier dans les projets impliquant plusieurs services ou outils externes. Il s'agit d'une solution puissante pour les équipes qui construisent une communication client-serveur robuste.

Option 4 : Scaler - Le préféré de Tim pour les tests d'API

Tim présente Scaler UI comme son préféré parmi toutes les options, le décrivant comme un mélange de Postman et de documentation dans le navigateur. Après avoir ajouté le paquet Scaler.AspNetCore, une seule ligne de code (app.MapScalerApiReference()) est nécessaire pour activer l'interface.

Scaler prend en charge une interactivité complète, y compris l'exécution de requêtes avec des paramètres de requête, des en-têtes et des cookies. L'outil se distingue par son retour d'information en temps réel : il renvoie instantanément le temps de réponse, les en-têtes et les résultats.

Scaler se distingue par sa capacité à générer des commandes curl et des extraits de code client pour différents langages (PHP, Node, Python, C# via HttpClient et RestSharp). Tim trouve cette traduction particulièrement utile pour copier et coller rapidement les appels d'API pendant le développement.

Scaler permet également de basculer entre les modes clair et foncé, ce qui en fait une plateforme de documentation API conviviale qui peut encore être améliorée. En tant que plateforme API open source, Scaler continue d'évoluer grâce à une maintenance active et à un fort intérêt de la part de la communauté.

Réflexions finales : Les options apportent de la flexibilité

Dans les dernières minutes de la vidéo, Tim souligne que la suppression de Swagger UI des modèles web .NET peut sembler un pas en arrière, mais qu'il s'agit en fait d'une occasion d'adopter des solutions modernes et mieux adaptées. Ce changement s'aligne sur les cycles de publication rapides de Microsoft, où les fonctionnalités sont de plus en plus modulaires et ciblées.

Le support OpenAPI agit désormais davantage comme un support de citoyen de première classe que comme une implémentation native rigide. Vous êtes libre de combiner les outils en fonction des besoins de votre projet, qu'il s'agisse de tests interactifs avec Scaler, de génération de code client avec NSwag ou d'une sortie propre avec ReDoc.

Tim encourage les développeurs à explorer ces outils, à voir lequel correspond à leur flux de travail, et peut-être même à utiliser plusieurs interfaces utilisateur pour différents environnements (par exemple, une pour le développement et une autre pour la documentation publique). Le fait que toutes ces options prennent en charge les spécifications OpenAPI et Swagger signifie que vous n'êtes pas enfermé dans un fournisseur ou un flux de travail unique.

Conclusion

Grâce à la suppression de l'interface Swagger par défaut dans .NET 9, les développeurs ont désormais la liberté de choisir le meilleur outil pour leurs besoins de documentation OpenAPI. Que vous documentiez des API HTTP, que vous serviez des outils externes ou que vous souteniez le développement interne, il existe une solution qui correspond à vos objectifs.

Avec des outils tels que Swagger UI, ReDoc, NSwag et Scaler, la documentation et le test des API n'ont jamais été aussi personnalisables et conviviaux pour les développeurs. Comme Tim Corey nous le montre dans sa vidéo, il suffit de quelques paquets, de quelques lignes de code et de la volonté d'explorer les outils qui conviennent le mieux à votre application et à votre équipe.