Bien démarrer avec Swashbuckle et ASP.NET Core

  • Article
  • 22 minutes de lecture

Swashbuckle repose sur trois composants principaux :

  • Swashbuckle.AspNetCore.Swagger : modèle objet Et intergiciel Swagger pour exposer SwaggerDocument des objets en tant que JSpoints de terminaison ON.

  • Swashbuckle.AspNetCore.SwaggerGen : générateur Swagger qui crée des objets SwaggerDocument directement à partir de vos routes, contrôleurs et modèles. Il est généralement combiné avec l’intergiciel de point de terminaison Swagger pour exposer automatiquement Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: version incorporée de l’outil IU Swagger. Il interprète Swagger JSON pour créer une expérience riche et personnalisable pour décrire les fonctionnalités de l’API web. Il intègre des ateliers de test pour les méthodes publiques.

Installation de package

Vous pouvez ajouter Swashbuckle en adoptant l’une des approches suivantes :

  • À partir de la fenêtre Console du Gestionnaire de package :

    • Accédez à Afficher les> autresconsoles du Gestionnaire de packageWindows>

    • Accédez au répertoire dans lequel le .csproj fichier existe.

    • Exécutez la commande suivante :

      Install-Package Swashbuckle.AspNetCore -Version 6.2.3

  • À partir de la boîte de dialogue Gérer les packages NuGet :

    • Cliquez avec le bouton droit sur le projet dans Explorateur de solutions>Gérer les packages NuGet
    • Affectez la valeur « nuget.org » à Source du package.
    • Vérifiez que l’option « Inclure la version préliminaire » est activée
    • Entrez « Swashbuckle.AspNetCore » dans la zone de recherche.
    • Sélectionnez le package « Swashbuckle.AspNetCore » le plus récent sous l’onglet Parcourir et cliquez sur Installer.

Ajouter et configurer l’intergiciel (middleware) Swagger

Ajoutez le générateur Swagger à la collection de services dans Program.cs:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

L’appel à AddEndpointsApiExplorer indiqué dans l’exemple précédent est requis uniquement pour les API minimales. Pour plus d’informations, consultez ce billet StackOverflow.

Activez l’intergiciel pour servir le document ON généré JSet l’interface utilisateur Swagger, également dans Program.cs:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Le code précédent ajoute l’intergiciel Swagger uniquement si l’environnement actuel est défini sur Développement. L’appel UseSwaggerUI de méthode active l’intergiciel de fichier statique.

Lancez l’application et accédez à https://localhost:<port>/swagger/v1/swagger.json. Le document généré décrivant les points de terminaison s’affiche comme indiqué dans la spécification OpenAPI (openapi.json).

L’interface utilisateur Swagger se trouve à l’adresse https://localhost:<port>/swagger. Explorez l’API via l’interface utilisateur Swagger et incorporez-la dans d’autres programmes.

Conseil

Pour utiliser l’IU Swagger à la racine de l’application (https://localhost:<port>/), définissez la propriété RoutePrefix sur une chaîne vide :

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    options.RoutePrefix = string.Empty;
});

Si vous utilisez des répertoires avec IIS ou un proxy inverse, définissez le point de terminaison Swagger sur un chemin relatif avec le préfixe ./. Par exemple : ./swagger/v1/swagger.json. L’utilisation /swagger/v1/swagger.json indique à l’application de rechercher le JSfichier ON à la racine réelle de l’URL (plus le préfixe d’itinéraire, le cas échéant). Par exemple, utilisez https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json au lieu de https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Notes

Par défaut, Swashbuckle génère et expose Swagger JSON dans la version 3.0 de la spécification, officiellement appelée spécification OpenAPI. Pour prendre en charge la compatibilité descendante, vous pouvez choisir d’exposer JSON au format 2.0 à la place. Ce format 2.0 est important pour les intégrations telles que Microsoft Power Apps et Microsoft Flow qui prennent actuellement en charge OpenAPI version 2.0. Pour choisir le format 2.0, définissez la SerializeAsV2 propriété dans Program.cs:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Personnaliser et étendre

Swagger fournit des options pour documenter le modèle objet et personnaliser l’interface utilisateur en fonction de votre thème.

Informations sur l’API et description

L’action de configuration passée à la AddSwaggerGen méthode ajoute des informations telles que l’auteur, la licence et la description.

Dans Program.cs, importez l’espace de noms suivant pour utiliser la OpenApiInfo classe :

using Microsoft.OpenApi.Models;

À l’aide de la OpenApiInfo classe , modifiez les informations affichées dans l’interface utilisateur :

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

L’IU Swagger affiche les informations de la version :

Interface utilisateur Swagger avec des informations de version : description, auteur et licence.

Commentaires XML

Vous pouvez activer les commentaires XML en adoptant l’une des approches suivantes :

  • Cliquez avec le bouton droit sur le projet dans Explorateur de solutions, puis sélectionnez Edit <project_name>.csproj.
  • Ajoutez GenerateDocumentationFile au .csproj fichier :
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

L’activation de commentaires XML fournit des informations de débogage sur les membres et types publics non documentés. Les membres et types non documentés sont indiqués par le message d’avertissement. Par exemple, le message suivant indique une violation du code d’avertissement 1591 :

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Pour supprimer des avertissements à l’échelle d’un projet, définissez une liste séparée par des points-virgules de codes d’avertissement à ignorer dans le fichier de projet. L’ajout des codes d’avertissement à $(NoWarn); applique aussi les valeurs par défaut C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Pour supprimer des avertissements uniquement pour des membres spécifiques, placez le code dans les directives de préprocesseur #pragma warning. Cette approche est utile pour le code qui ne doit pas être exposé via la documentation de l’API. Dans l’exemple suivant, le code d’avertissement CS1591 est ignoré pour l’ensemble TodoContext de la classe. La mise en œuvre de code d’avertissement est restaurée à la fin de la définition de classe. Spécifier plusieurs codes d’avertissement avec une liste délimitée par des virgules.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Configurez Swagger de façon à utiliser le fichier XML généré avec les instructions précédentes. Pour les systèmes d’exploitation Linux ou non-Windows, les chemins et les noms de fichiers peuvent respecter la casse. Par exemple, un TodoApi.XML fichier est valide sur Windows, mais pas Sur CentOS.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Dans le code précédent, Reflection est utilisé pour générer un nom de fichier XML correspondant à celui du projet d’API web. La propriété AppContext.BaseDirectory est utilisée pour construire le chemin du fichier XML. Certaines fonctionnalités de Swagger (par exemple, les schémas de paramètres d’entrée ou les méthodes HTTP et les codes de réponse issus des attributs respectifs) fonctionnent sans fichier de documentation XML. Pour la plupart des fonctionnalités cependant, à savoir les résumés de méthode et les descriptions des paramètres et des codes de réponse, l’utilisation d’un fichier XML est obligatoire.

Quand vous ajoutez des commentaires précédés de trois barres obliques à une action, Swagger UI ajoute la description à l’en-tête de la section. Ajoutez un <élément résumé> au-dessus de l’action Delete :

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

L’IU Swagger affiche le texte interne de l’élément <summary> du code précédent :

Interface utilisateur Swagger montrant le commentaire XML « Deletes a specific TodoItem. » pour la méthode DELETE.

L’interface utilisateur est pilotée par le schéma ON généré JS:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Ajoutez un <élément de remarques> à la documentation de la Create méthode d’action. Il complète les informations spécifiées dans l’élément <summary> et fournit une interface utilisateur Swagger plus robuste. Le <remarks> contenu de l’élément peut être composé de texte, JSON ou XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Notez les améliorations de l’IU avec ces commentaires supplémentaires :

Interface utilisateur Swagger avec des commentaires supplémentaires affichés.

Annotations de données

Marquez le modèle avec des attributs, trouvés dans l’espace System.ComponentModel.DataAnnotations de noms, pour aider à piloter les composants de l’interface utilisateur Swagger.

Ajoutez l’attribut [Required] à la propriété Name de la classe TodoItem :

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

La présence de cet attribut modifie le comportement de l’interface utilisateur et modifie le schéma ON sous-jacent JS:

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

Ajoutez l’attribut [Produces("application/json")] au contrôleur d’API. Son objectif est de déclarer que les actions du contrôleur prennent en charge une réponse dont le type de contenu est application/json :

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

La liste déroulante Type de média sélectionne ce type de contenu comme type de contenu par défaut pour les actions GET du contrôleur :

Interface utilisateur de Swagger avec le type de contenu de réponse par défaut

À mesure que l’utilisation des annotations de données dans l’API web augmente, l’interface utilisateur et les pages d’aide de l’API deviennent de plus en plus descriptives et utiles.

Décrire des types de réponse

Les développeurs qui consomment une API web sont les plus préoccupés par ce qui est retourné, en particulier les types de réponse et les codes d’erreur (si ce n’est pas standard). Les types de réponse et les codes d’erreur sont décrits dans les commentaires XML et les annotations de données.

L’action Create retourne un code d’état HTTP 201 en cas de réussite. Un code d’état HTTP 400 est retourné quand le corps de la demande postée est null. Sans documentation appropriée dans l’interface utilisateur de Swagger, le consommateur n’a pas connaissance de ces résultats attendus. Pour résoudre ce problème, ajoutez les lignes en surbrillance de l’exemple suivant :

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

L’interface utilisateur de Swagger documente maintenant clairement les codes de réponse HTTP attendus :

Interface utilisateur Swagger montrant la description de la classe de réponse POST « Retourne l’élément Todo nouvellement créé » et « 400 - Si l’élément est null » pour le code d’état et la raison sous Messages de réponse.

Les conventions peuvent être utilisées comme alternative à la décoration explicite d’actions individuelles avec [ProducesResponseType]. Pour plus d'informations, consultez Utiliser les conventions d’API web.

Pour prendre en charge la [ProducesResponseType] décoration, le package Swashbuckle.AspNetCore.Annotations propose des extensions pour activer et enrichir les métadonnées de réponse, de schéma et de paramètre.

Personnaliser l’interface utilisateur

L’interface utilisateur par défaut est à la fois fonctionnelle et présentable. Toutefois, les pages de documentation d’API doivent représenter votre marque ou thème. La personnalisation des composants Swashbuckle nécessite d’ajouter les ressources qui traitent les fichiers statiques et de générer la structure de dossiers pour héberger ces fichiers.

Activez le middleware de fichiers statiques :

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Pour injecter des feuilles de style CSS supplémentaires, ajoutez-les au dossier wwwroot du projet et spécifiez le chemin relatif dans les options d’intergiciel :

app.UseSwaggerUI(options =>
{
    options.InjectStylesheet("/swagger-ui/custom.css");
});

Ressources supplémentaires

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Swashbuckle repose sur trois composants principaux :

  • Swashbuckle.AspNetCore.Swagger : modèle objet Et intergiciel Swagger pour exposer SwaggerDocument des objets en tant que JSpoints de terminaison ON.

  • Swashbuckle.AspNetCore.SwaggerGen : générateur Swagger qui crée des objets SwaggerDocument directement à partir de vos routes, contrôleurs et modèles. Il est généralement combiné avec l’intergiciel de point de terminaison Swagger pour exposer automatiquement Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: version incorporée de l’outil IU Swagger. Il interprète Swagger JSON pour créer une expérience riche et personnalisable pour décrire les fonctionnalités de l’API web. Il intègre des ateliers de test pour les méthodes publiques.

Installation de package

Vous pouvez ajouter Swashbuckle en adoptant l’une des approches suivantes :

  • À partir de la fenêtre Console du Gestionnaire de package :

    • Accédez à Afficher les> autresconsoles du Gestionnaire de packageWindows>

    • Accédez au répertoire dans lequel le TodoApi.csproj fichier existe.

    • Exécutez la commande suivante :

      Install-Package Swashbuckle.AspNetCore -Version 5.6.3

  • À partir de la boîte de dialogue Gérer les packages NuGet :

    • Cliquez avec le bouton droit sur le projet dans Explorateur de solutions>Gérer les packages NuGet
    • Affectez la valeur « nuget.org » à Source du package.
    • Vérifiez que l’option « Inclure la version préliminaire » est activée
    • Entrez « Swashbuckle.AspNetCore » dans la zone de recherche.
    • Sélectionnez le package « Swashbuckle.AspNetCore » le plus récent sous l’onglet Parcourir et cliquez sur Installer.

Ajouter et configurer l’intergiciel (middleware) Swagger

Ajoutez le générateur Swagger à la collection de services dans la méthode Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

Dans la Startup.Configure méthode , activez l’intergiciel pour traiter le document ON généré JSet l’interface utilisateur Swagger :

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
    app.UseSwaggerUI();

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Notes

Swashbuckle s’appuie sur MVC pour découvrir les routes et les points de Microsoft.AspNetCore.Mvc.ApiExplorer terminaison. Si le projet appelle AddMvc, les itinéraires et les points de terminaison sont détectés automatiquement. Lors de l’appel AddMvcCorede , la AddApiExplorer méthode doit être appelée explicitement. Pour plus d’informations, consultez Swashbuckle, ApiExplorer et Routage.

L’appel de méthode UseSwaggerUI précédent active le middleware (intergiciel) des fichiers statiques. Si vous ciblez .NET Framework ou .NET Core 1.x, ajoutez le package NuGet Microsoft.AspNetCore.StaticFiles au projet.

Lancez l’application et accédez à http://localhost:<port>/swagger/v1/swagger.json. Le document généré décrivant les points de terminaison s’affiche comme indiqué dans la spécification OpenAPI (openapi.json).

L’interface utilisateur Swagger se trouve à l’adresse http://localhost:<port>/swagger. Explorez l’API via l’interface utilisateur Swagger et incorporez-la dans d’autres programmes.

Conseil

Pour utiliser l’IU Swagger à la racine de l’application (http://localhost:<port>/), définissez la propriété RoutePrefix sur une chaîne vide :

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

Si vous utilisez des répertoires avec IIS ou un proxy inverse, définissez le point de terminaison Swagger sur un chemin relatif avec le préfixe ./. Par exemple : ./swagger/v1/swagger.json. L’utilisation /swagger/v1/swagger.json indique à l’application de rechercher le JSfichier ON à la racine réelle de l’URL (plus le préfixe d’itinéraire, le cas échéant). Par exemple, utilisez http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json au lieu de http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Notes

Par défaut, Swashbuckle génère et expose Swagger JSON dans la version 3.0 de la spécification, officiellement appelée spécification OpenAPI. Pour prendre en charge la compatibilité descendante, vous pouvez choisir d’exposer JSON au format 2.0 à la place. Ce format 2.0 est important pour les intégrations telles que Microsoft Power Apps et Microsoft Flow qui prennent actuellement en charge OpenAPI version 2.0. Pour choisir le format 2.0, définissez la SerializeAsV2 propriété dans Startup.Configure:

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger(c =>
    {
        c.SerializeAsV2 = true;
    });

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Personnaliser et étendre

Swagger fournit des options pour documenter le modèle objet et personnaliser l’interface utilisateur en fonction de votre thème.

Dans la classe Startup, ajoutez les espaces de noms suivants :

using System;
using System.Reflection;
using System.IO;

Informations sur l’API et description

L’action de configuration transmise à la méthode AddSwaggerGen ajoute des informations comme l’auteur, la license et la description :

Dans la classe Startup, importez l’espace de noms suivant pour utiliser la classe OpenApiInfo :

using Microsoft.OpenApi.Models;

À l’aide de la OpenApiInfo classe , modifiez les informations affichées dans l’interface utilisateur :

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });
});

L’IU Swagger affiche les informations de la version :

Interface utilisateur Swagger avec des informations de version : description, auteur et voir plus de lien.

Commentaires XML

Vous pouvez activer les commentaires XML en adoptant l’une des approches suivantes :

  • Cliquez avec le bouton droit sur le projet dans Explorateur de solutions, puis sélectionnez Edit <project_name>.csproj.
  • Ajoutez manuellement les lignes en surbrillance au .csproj fichier :
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

L’activation de commentaires XML fournit des informations de débogage sur les membres et types publics non documentés. Les membres et types non documentés sont indiqués par le message d’avertissement. Par exemple, le message suivant indique une violation du code d’avertissement 1591 :

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Pour supprimer des avertissements à l’échelle d’un projet, définissez une liste séparée par des points-virgules de codes d’avertissement à ignorer dans le fichier de projet. L’ajout des codes d’avertissement à $(NoWarn); applique aussi les valeurs par défaut C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Pour supprimer des avertissements uniquement pour des membres spécifiques, placez le code dans les directives de préprocesseur #pragma warning. Cette approche est utile pour le code qui ne doit pas être exposé via la documentation de l’API. Dans l’exemple suivant, le code d’avertissement CS1591 est ignoré pour l’ensemble Program de la classe. La mise en œuvre de code d’avertissement est restaurée à la fin de la définition de classe. Spécifier plusieurs codes d’avertissement avec une liste délimitée par des virgules.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#pragma warning restore CS1591
}

Configurez Swagger de façon à utiliser le fichier XML généré avec les instructions précédentes. Pour les systèmes d’exploitation Linux ou non-Windows, les chemins et les noms de fichiers peuvent respecter la casse. Par exemple, un TodoApi.XML fichier est valide sur Windows, mais pas CentOS.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Dans le code précédent, reflection est utilisé pour générer un nom de fichier XML correspondant à celui du projet d’API web. La propriété AppContext.BaseDirectory est utilisée pour construire le chemin du fichier XML. Certaines fonctionnalités de Swagger (par exemple, les schémas de paramètres d’entrée ou les méthodes HTTP et les codes de réponse issus des attributs respectifs) fonctionnent sans fichier de documentation XML. Pour la plupart des fonctionnalités cependant, à savoir les résumés de méthode et les descriptions des paramètres et des codes de réponse, l’utilisation d’un fichier XML est obligatoire.

Quand vous ajoutez des commentaires précédés de trois barres obliques à une action, Swagger UI ajoute la description à l’en-tête de la section. Ajoutez un <élément récapitulatif> au-dessus de l’action Delete :

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

L’IU Swagger affiche le texte interne de l’élément <summary> du code précédent :

Interface utilisateur Swagger affichant le commentaire XML « Supprime un TodoItem spécifique » pour la méthode DELETE.

L’interface utilisateur est pilotée par le schéma ON généré JS:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "type": "integer",
            "format": "int64"
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
}

Ajoutez un <élément de remarque> à la documentation de la Create méthode d’action. Il complète les informations spécifiées dans l’élément <summary> et fournit une interface utilisateur Swagger plus robuste. Le <remarks> contenu de l’élément peut se composer de texte, JSON ou XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Notez les améliorations de l’IU avec ces commentaires supplémentaires :

Interface utilisateur Swagger avec des commentaires supplémentaires affichés.

Annotations de données

Marquez le modèle avec des attributs, trouvés dans l’espace System.ComponentModel.DataAnnotations de noms, pour aider à piloter les composants de l’interface utilisateur Swagger.

Ajoutez l’attribut [Required] à la propriété Name de la classe TodoItem :

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

La présence de cet attribut modifie le comportement de l’interface utilisateur et modifie le schéma ON sous-jacent JS:

"definitions": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "format": "int64",
                "type": "integer"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "default": false,
                "type": "boolean"
            }
        }
    }
},

Ajoutez l’attribut [Produces("application/json")] au contrôleur d’API. Son objectif est de déclarer que les actions du contrôleur prennent en charge une réponse dont le type de contenu est application/json :

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

La liste déroulante Type de contenu de réponse sélectionne ce type de contenu comme type de contenu par défaut pour les actions GET du contrôleur :

Interface utilisateur Swagger avec le type de contenu de réponse par défaut.

À mesure que l’utilisation des annotations de données dans l’API web augmente, l’interface utilisateur et les pages d’aide de l’API deviennent de plus en plus descriptives et utiles.

Décrire des types de réponse

Les développeurs qui consomment une API web sont les plus préoccupés par ce qui est retourné, en particulier les types de réponse et les codes d’erreur (si ce n’est pas standard). Les types de réponse et les codes d’erreur sont décrits dans les commentaires XML et les annotations de données.

L’action Create retourne un code d’état HTTP 201 en cas de réussite. Un code d’état HTTP 400 est retourné quand le corps de la demande postée est null. Sans documentation appropriée dans l’interface utilisateur de Swagger, le consommateur n’a pas connaissance de ces résultats attendus. Pour résoudre ce problème, ajoutez les lignes en surbrillance de l’exemple suivant :

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

L’interface utilisateur de Swagger documente maintenant clairement les codes de réponse HTTP attendus :

L’interface utilisateur Swagger montrant la description de la classe de réponse POST « Retourne l’élément Todo nouvellement créé » et « 400 - Si l’élément est null » pour le code d’état et la raison sous Messages de réponse.

Dans ASP.NET Core 2.2 ou une version ultérieure, les conventions peuvent être utilisées comme alternatives à la décoration explicites des actions individuelles avec [ProducesResponseType]. Pour plus d'informations, consultez Utiliser les conventions d’API web.

Pour prendre en charge la [ProducesResponseType] décoration, le package Swashbuckle.AspNetCore.Annotations propose des extensions pour activer et enrichir les métadonnées de réponse, de schéma et de paramètre.

Personnaliser l’interface utilisateur

L’interface utilisateur par défaut est à la fois fonctionnelle et présentable. Toutefois, les pages de documentation d’API doivent représenter votre marque ou thème. La personnalisation des composants Swashbuckle nécessite d’ajouter les ressources qui traitent les fichiers statiques et de générer la structure de dossiers pour héberger ces fichiers.

Si vous ciblez le .NET Framework ou .NET Core 1.x, ajoutez le package NuGet Microsoft.AspNetCore.StaticFiles au projet :

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />

Le package NuGet précédent est déjà installé si vous ciblez .NET Core 2.x et que vous utilisez le métapackage.

Activez le middleware de fichiers statiques :

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Pour injecter des feuilles de style CSS supplémentaires, ajoutez-les au dossier wwwroot du projet et spécifiez le chemin d’accès relatif dans les options d’intergiciel :

app.UseSwaggerUI(c =>
{
     c.InjectStylesheet("/swagger-ui/custom.css");
}

Ressources supplémentaires