Skip to main content

Guide Pratique : Générer la Documentation d'API avec Swashbuckle dans .NET (Contrat d'Interface avec OpenAPI)

La documentation des APIs se fait entièrement via la documentation dansa le code source de Swagger/OpenAPI via du XML ou des annotations sur les modèles et les controllers.

Cette page présente sa mise en place dans le projet et sur chacun des controllers d'APIs.

Les grandes étapes de la mise en oeuvre :

  • Installation et Configuration de Base : Ajout du package NuGet Swashbuckle.AspNetCore et configuration des services et du middleware dans Startup.cs pour activer la génération de la documentation (swagger.json) et l'interface utilisateur web. Ce processus diffère sleon que ce soit une application ABP ou ASP.NET Core standard, les deux sont détaillés.

  • Exploration de l'UI Swagger : <url_de_mon_site>/swagger pour se connecter interface auto-générée, qui liste tous les points de terminaison (endpoints) de l'API avec leurs verbes HTTP, leurs routes, leurs paramètres et leurs schémas de réponse.

  • Fonctionnalité de Test ("Try it out") : Utilisation de l'interface Swagger pour tester directement les points de terminaison de l'API, en envoyant des requêtes et en visualisant les réponses réelles, ce qui est très utile pour le développement et le débogage.

  • Enrichissement de la Documentation : Activation de la génération de fichiers de documentation XML dans le projet (.csproj) et utilisation de commentaires XML spécifiques (<summary_>, <remarks>, <response>) directement sur les méthodes du contrôleur pour ajouter des descriptions, des exemples de requêtes/réponses personnalisés et des codes de statut HTTP détaillés.

Installation de Swagger/Swashbuckle

La procédure diverge s'il s'agit d'une application ASP.NET Core ou ABP.

Pour une application ASP.NET Core​

Étape 1 : Installation du Package​

  • Installez Swashbuckle via le gestionnaire de packages NuGet.
dotnet add package Swashbuckle.AspNetCore

Étape 2 : Configuration dans Startup.cs​

Modifiez votre fichier Startup.cs pour enregistrer les services Swagger et activer le middleware.

  • Dans ConfigureServices(IServiceCollection services) :

Ajoutez le générateur Swagger pour qu'il découvre les routes et les modèles de votre API.

public void ConfigureServices(IServiceCollection services)
{
   services.AddControllers();
        
   // Enregistrer le générateur Swagger
   services.AddSwaggerGen();
}
  • Dans Configure(IApplicationBuilder app, IWebHostEnvironment env) :

Activez le middleware pour servir la documentation JSON générée et l'interface utilisateur Swagger.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
   // ... autres middlewares
        
   // 1. Sert le document JSON généré (swagger.json)
   app.UseSwagger();
        
   // 2. Sert l'interface utilisateur de Swagger
   app.UseSwaggerUI(c =&gt;
   {
      c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mon API V1");
   });
        
   // ... autres middlewares
}

Lancez votre application et naviguez vers /swagger pour voir la documentation de base.

Étape 3 : Enrichir la Documentation avec les Commentaires XML​

Pour ajouter des descriptions, des exemples et des détails sur les réponses, utilisez les commentaires XML.

  • Activer la Génération du Fichier XML :
    Modifiez votre fichier de projet (.csproj) et ajoutez la ligne suivante dans un <PropertyGroup>.
        &lt;PropertyGroup&gt;
          &lt;TargetFramework&gt;netcoreapp3.1&lt;/TargetFramework&gt;
          &lt;!-- Cette ligne active la génération du fichier de documentation XML --&gt;
          &lt;GenerateDocumentationFile&gt;true&lt;/GenerateDocumentationFile&gt;
        &lt;/PropertyGroup&gt;

Vous pouvez consulter toutes les options de projet dans la documentation MS Learn.

  • Intégrer le Fichier XML dans Swagger :

    Mettez à jour la configuration de AddSwaggerGen dans Startup.cs pour qu'il utilise le fichier XML généré.

        services.AddSwaggerGen(c =&gt;
        {
            // ... autre configuration
        
            // Configurer Swagger pour utiliser le fichier XML généré
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });

Pour une application ABP​

Etape 1 : Générer votre code avec ABP Studio​

Tout devrait être intégrer dans la solution générée.

Etape 2 : Configurer Swashbuckle​

private static void ConfigureSwagger(ServiceConfigurationContext context, IConfiguration configuration)
{
    context.Services.AddAbpSwaggerGenWithOidc(
        configuration["AuthServer:Authority"]!,
        ["PortailClients"],
        [AbpSwaggerOidcFlows.AuthorizationCode],
        null,
        options =&gt;
        {
            options.SwaggerDoc("v1", new OpenApiInfo { Title = "PortailClients API", Version = "v1" });
            options.DocInclusionPredicate((docName, description) =&gt; true);
            options.CustomSchemaIds(type =&gt; type.FullName);
        });
}

Commenter son API dans le code en utilisant XML

Ajoutez des commentaires /// au-dessus de vos méthodes de contrôleur pour les documenter.

  • &lt;summary&gt; pour la description générale :
        /// &lt;summary&gt;
        /// Récupère une personne spécifique par son identifiant.
        /// &lt;/summary&gt;
        [HttpGet("getPerson")]
        public ActionResult&lt;PersonModel&gt; GetPersonById(int id)
        {
            // ...
        }

  • &lt;remarks&gt; pour les exemples de requêtes/réponses :

    Utilisez cette balise pour fournir des exemples clairs. L'indentation est importante pour le rendu.

/// &lt;remarks&gt;
/// Exemple de requête :
///
/// POST /Person/postPerson
/// {
///        "id": 1,
///        "firstName": "Tim",
///        "lastName": "James",
///        "address": "NYC Street 12"
///     }
///
/// &lt;/remarks&gt;
[HttpPost("postPerson")]
public void postPerson([FromBody] PersonModel personModel)
{
   // ...
}

  • &lt;response&gt; pour documenter les codes de statut :

    Spécifiez les différents codes de réponse possibles pour un point de terminaison.

/// &lt;summary&gt;
/// Crée une nouvelle personne.
/// &lt;/summary&gt;
/// &lt;response code="201"&gt;Retourne si la personne a été créée avec succès.&lt;/response&gt;
/// &lt;response code="400"&gt;Retourne si les données fournies sont incorrectes.&lt;/response&gt;
[HttpPost("postPerson")]
public void postPerson([FromBody] PersonModel personModel)
{
   // ...
}

/// &lt;summary&gt;  
/// Ajoute un nouvel étudiant.
/// &lt;/summary&gt;  
/// &lt;param name="student"&gt;LModèle Student&lt;/param&gt;  
/// &lt;remarks&gt;Insert un nouvel étudiant dans le système&lt;/remarks&gt;  
/// &lt;response code="400"&gt;Bad request&lt;/response&gt;  
/// &lt;response code="500"&gt;Internal server error&lt;/response&gt;  
[Route("")]  
[ResponseType(typeof(Student))]  
public IHttpActionResult Post(Student student)  
{  
   // ...  
}

Export des contrats d'interface en PDF

Pour exporter la documentation de Swagger, nous utilisons la CI avec l'app NPM :

Autres solutions identiées :

⚠️ Ces outils n'ont pas été testés en production. Merci de faire des tests etr de communiquer les retours, exemples, d'utilisation, problème de sécurité, etc;