Ce post a été modifié pour la dernière fois par QWERTYU le 12-04-2019 à 14:24
IntroductionAprès avoir utilisé asp.net Core pour le développement d’API, rédiger de la documentation API doit être une tâche pénible pour les programmeurs, mais la documentation doit être rédigée, et s’il n’y a pas d’exigences spécifiques pour le format de la documentation, la documentation finale dépend entièrement de l’humeur du développeur. Ou plus détaillés, ou plus simples. Existe-t-il donc un moyen rapide et efficace de créer une documentation API ? La réponse est oui, Swagger est l’un des outils de génération de documentation des API REST les plus populaires !
Pourquoi utiliser Swagger comme outil de génération de documentation pour les API REST- Swagger peut générer une console API interactive que les développeurs peuvent utiliser pour apprendre et expérimenter rapidement avec les API.
- Swagger peut générer du code SDK client pour des implémentations sur une variété de plateformes différentes.
- Les fichiers Swagger peuvent être générés automatiquement à partir de commentaires de code sur de nombreuses plateformes différentes.
- Swagger possède une communauté solide avec de nombreux contributeurs solides.
Comment utiliser Swagger pour générer de la documentation API dans asp.net cœur ?- Swashbuckle.AspNetCore est un projet open source qui génère la documentation Swagger pour ASP.NET API Web Core.
- NSwag est un autre projet open source permettant d’intégrer ASP.NET Swagger UI ou ReDoc dans API Web Core. Il permet de générer du code client C# et TypeScript pour les API.
Voici un exemple de Swashbuckle.AspNetCoreQuels sont les composants d’un Swashbuckle ?- Swashbuckle.AspNetCore.Swagger : Expose l’objet SwagaggerDocument sous forme de modèle objet Swagger et de middleware pour les terminaux JSON.
- Swashbuckle.AspNetCore.SwaggerGen : Un générateur Swagger qui génère des objets SwagaggerDocument directement à partir de routes, contrôleurs et modèles. Il est souvent combiné avec le middleware de point d’extrémité Swagger pour exposer automatiquement le JSON Swagger.
- Swashbuckle.AspNetCore.SwaggerUI : Une version embarquée de l’outil Swagger UI. Il interprète Swagger JSON pour construire des expériences personnalisables et riches qui décrivent la fonctionnalité des API Web. Il inclut des outils de test intégrés pour les méthodes courantes.
Comment installer Swashbuckle avec vs2017 ?
La première méthode : installer depuis la fenêtre de la console du gestionnaire de paquets
- Aller dans Vues > autres consoles du gestionnaire de paquets Windows >
- Naviguez jusqu’au répertoire contenant le fichier TodoApi.csproj
- Veuillez exécuter la commande suivante · Install-Package Swashbuckle.AspNetCore
-
Deuxième méthode : depuis la boîte de dialogue Gérer les paquets NuGet :- Faites un clic droit sur le projet dans l’Explorateur de solutions > Gérer les packages NuGet
- Définir la source du paquet à nuget.org
- Tapez « Swashbuckle.AspNetCore » dans la barre de recherche
- Sélectionnez le package Swashbuckle.AspNetCore dans l’onglet Parcourir et cliquez sur Installer
-
Ajouter et configurer le middleware SwaggerIntroduisez d’abord l’espace de noms : Ajoutez le générateur Swagger à la collection de services dans la méthode Startup.ConfigureServices : àDémarrer.Configureméthode, permettre au middleware de servir le document JSON généré et l’interface utilisateur Swagger :
Lance l’application et accède-lahttps://localhost :<port>/swagger/v1/swagger.json。 La documentation résultante décrivant le point d’extrémité est affichée au format JSON comme suit.
Disponiblehttps://localhost :<port>/assuranceLocalisez l’interface Swagger. Parcourez la documentation de l’API via l’interface Swagger comme indiqué ci-dessous.
Pour appliquer la racine (http://localhost :<port>/) pour fournir l’interface Swagger, veuillez indiquer leRoutePrefixeLa propriété est définie sur une chaîne vide :
Utilisation avancée de Swagger (personnalisation et extensions)Utilisez Swagger pour ajouter des informations explicatives à la documentation de l’APILes opérations de configuration suivantes sont effectuées dans la méthode AddSwaggerGen, qui ajoute des informations telles que l’auteur, la licence et la description : Les informations sur la version d’affichage de l’interface utilisateur de wagger sont présentées dans la figure suivante : Ajouter des commentaires aux méthodes d’interfaceCliquons d’abord sur l’API, développons comme montré dans la figure ci-dessous, ne peut-il pas y avoir de commentaires, comment ajouter des commentaires ? Ajoutez les commentaires du document avec trois/comme montré dans l’image ci-dessous, comme indiqué ci-dessous Ensuite, lancez le projet et retournez dans l’interface swagger pour voir si le commentaire apparaît Toujours pas apparu, ne t’inquiète pas, regarde en bas ! Activer les annotations XMLVous pouvez permettre d’activer les annotations XML en utilisant les méthodes suivantes : - Faites un clic droit sur le projet dans l’Explorateur de solutions et sélectionnez Propriétés
- Regardez la boîte Fichier du document XML sous la section Sortie de l’onglet Build
-
L’activation des annotations XML fournit des informations de débogage pour les types et membres communs non documentés. Si de nombreux messages d’avertissement apparaissent, par exemple, le message suivant indique une violation du code d’avertissement 1591 :
Que faire si vous avez un TOC et souhaitez annuler l’avertissement ? Vous pouvez annuler comme montré sur l’image ci-dessous
Notez le chemin du fichier document xml généré ci-dessus,
Note: 1. Pour les systèmes d’exploitation Linux ou non Windows, les noms et chemins des fichiers sont sensibles à la casse. Par exemple, un fichier « SwaggerDemo.xml » fonctionne sous Windows, mais pas sur CentOS. 2. Pour obtenir le chemin d’application, il est recommandé d’utiliser AppContext.BaseDirectory pour l’obtenir Reconstruisez et lancez le projet pour voir si les commentaires apparaissent D’après l’opération ci-dessus, on peut résumer que l’interface Swagger affiche le <summary> texte interne des éléments du code de commentaire ci-dessus sous forme de commentaires API de grande taille ! Bien sûr, vous pouvez aussi ajouter l’élément remarques à la documentation Obtenir des instructions. Elle peut compléter <summary> les informations spécifiées dans l’élément et offrir une interface Swagger plus fiable. <remarks> Le contenu des éléments peut contenir du texte, du JSON ou du XML. Le code est le suivant : Testez l’interface API avec SwaggerUIDébogons l’interface via SwaggerUI à travers un petit exemple
- Cliquez sur une interface API à tester, puis cliquez sur le bouton « Essayer » à gauche et à droite de Paramètres
- Entrez un paramètre dans la boîte de texte du paramètre qui apparaît, comme montré sur l’image suivante, saisissez le paramètre 2
- Cliquez sur le bouton Exécuter, et la Réponse formatée présentée ci-dessous apparaîtra, comme illustré dans la figure ci-dessous
Voilà, c’est tout pour le tutoriel d’aujourd’hui sur l’utilisation de Swagger pour générer la documentation API dans ASP.NET Core WebApi. J’espère qu’il vous sera utile d’apprendre à utiliser Swagger pour générer de la documentation API dans ASP.NET Core ! résuméCet article commence par le point sensible de la rédaction manuelle de la documentation API, puis mène à Swagger, un outil qui génère automatiquement la documentation API ! Ensuite, grâce à un texte et des images faciles à comprendre, nous montrerons comment utiliser SwaggerUI pour générer une documentation API dans une ASP.NET Core WebApi. Enfin, je vais introduire quelques utilisations avancées de Swagger dans ASP.NET Core ! J’espère que cela vous aidera à utiliser Swagger dans ASP.NET Core !
| 
Publié sur 12/04/2019 14:14:46
|
|
|
|
