Bien démarrer avec Swashbuckle et ASP.NET CoreGet started with Swashbuckle and ASP.NET Core

De Shayne Boyer et Scott AddieBy Shayne Boyer and Scott Addie

Afficher ou télécharger l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Swashbuckle repose sur trois composants principaux :There are three main components to Swashbuckle:

  • Swashbuckle.AspNetCore.Swagger : modèle objet Swagger et intergiciel (middleware) pour exposer des objets SwaggerDocument sous forme de points de terminaison JSON.Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.

  • Swashbuckle.AspNetCore.SwaggerGen : générateur Swagger qui crée des objets SwaggerDocument directement à partir de vos routes, contrôleurs et modèles.Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. Ce composant est généralement associé à l’intergiciel du point de terminaison Swagger pour exposer automatiquement un fichier JSON Swagger.It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: version incorporée de l’outil IU Swagger.Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. Il interprète le fichier JSON Swagger afin de créer une expérience enrichie et personnalisable permettant de décrire les fonctionnalités de l’API web.It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Il intègre des ateliers de test pour les méthodes publiques.It includes built-in test harnesses for the public methods.

Installation de packagePackage installation

Vous pouvez ajouter Swashbuckle en adoptant l’une des approches suivantes :Swashbuckle can be added with the following approaches:

  • À partir de la fenêtre Console du Gestionnaire de package :From the Package Manager Console window:

    • Accéder à la > console du gestionnaire deOther Windows > package WindowsGo to View > Other Windows > Package Manager Console

    • Accédez au répertoire où se trouve le fichier TodoApi.csproj.Navigate to the directory in which the TodoApi.csproj file exists

    • Exécutez la commande suivante :Execute the following command:

      Install-Package Swashbuckle.AspNetCore -Version 5.5.0
      
  • À partir de la boîte de dialogue Gérer les packages NuGet :From the Manage NuGet Packages dialog:

    • Cliquez avec le bouton droit sur le projet dans Explorateur de solutions > gérer les packages NuGetRight-click the project in Solution Explorer > Manage NuGet Packages
    • Affectez la valeur « nuget.org » à Source du package.Set the Package source to "nuget.org"
    • Vérifiez que l’option « Inclure la version préliminaire » est activéeEnsure the "Include prerelease" option is enabled
    • Entrez « Swashbuckle.AspNetCore » dans la zone de recherche.Enter "Swashbuckle.AspNetCore" in the search box
    • Sélectionnez le package « Swashbuckle.AspNetCore » le plus récent sous l’onglet Parcourir et cliquez sur Installer.Select the latest "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Ajouter et configurer l’intergiciel (middleware) SwaggerAdd and configure Swagger middleware

Ajoutez le générateur Swagger à la collection de services dans la méthode Startup.ConfigureServices :Add the Swagger generator to the services collection in the Startup.ConfigureServices method:

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

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}
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 méthode Startup.Configure, activez l’intergiciel pour traiter le document JSON généré et l’IU Swagger :In the Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:

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.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}
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.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

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

Notes

Swashbuckle s’appuie sur MVC Microsoft.AspNetCore.Mvc.ApiExplorer pour découvrir les itinéraires et les points de terminaison.Swashbuckle relies on MVC's Microsoft.AspNetCore.Mvc.ApiExplorer to discover the routes and endpoints. Si le projet appelle AddMvc , les itinéraires et les points de terminaison sont découverts automatiquement.If the project calls AddMvc, routes and endpoints are discovered automatically. Lors AddMvcCore de l’appel de, la AddApiExplorer méthode doit être appelée explicitement.When calling AddMvcCore, the AddApiExplorer method must be explicitly called. Pour plus d’informations, consultez Swashbuckle, ApiExplorer et routage.For more information, see Swashbuckle, ApiExplorer, and Routing.

L’appel de méthode UseSwaggerUI précédent active le middleware (intergiciel) des fichiers statiques.The preceding UseSwaggerUI method call enables the Static File Middleware. Si vous ciblez .NET Framework ou .NET Core 1. x, ajoutez le package NuGet Microsoft. AspNetCore. StaticFiles au projet.If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

Lancez l’application et accédez à http://localhost:<port>/swagger/v1/swagger.json.Launch the app, and navigate to 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.jssur).The generated document describing the endpoints appears as shown in OpenAPI specification (openapi.json).

L’interface utilisateur Swagger se trouve à l’adresse http://localhost:<port>/swagger.The Swagger UI can be found at http://localhost:<port>/swagger. Explorez l’API via l’interface utilisateur Swagger et incorporez-la dans d’autres programmes.Explore the API via Swagger UI and incorporate it in other programs.

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 :To serve the Swagger UI at the app's root (http://localhost:<port>/), set the RoutePrefix property to an empty string:

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 ./.If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. Par exemple : ./swagger/v1/swagger.json.For example, ./swagger/v1/swagger.json. L’utilisation de /swagger/v1/swagger.json indique à l’application de rechercher le fichier JSON à la racine réelle de l’URL (plus le préfixe de la route s’il est utilisé).Using /swagger/v1/swagger.json instructs the app to look for the JSON file at the true root of the URL (plus the route prefix, if used). 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.For example, use http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json instead of 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.By default, Swashbuckle generates and exposes Swagger JSON in version 3.0 of the specification—officially called the OpenAPI Specification. Pour prendre en charge la compatibilité descendante, vous pouvez choisir d’exposer JSON au format 2,0 à la place.To support backwards compatibility, you can opt into exposing JSON in the 2.0 format instead. 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.This 2.0 format is important for integrations such as Microsoft Power Apps and Microsoft Flow that currently support OpenAPI version 2.0. Pour choisir le format 2,0, définissez la SerializeAsV2 propriété dans Startup.Configure :To opt into the 2.0 format, set the SerializeAsV2 property in 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 étendreCustomize and extend

Swagger fournit des options pour documenter le modèle objet et personnaliser l’interface utilisateur en fonction de votre thème.Swagger provides options for documenting the object model and customizing the UI to match your theme.

Dans la classe Startup, ajoutez les espaces de noms suivants :In the Startup class, add the following namespaces:

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

Informations sur l’API et descriptionAPI info and description

L’action de configuration transmise à la méthode AddSwaggerGen ajoute des informations comme l’auteur, la license et la description :The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

Dans la classe Startup, importez l’espace de noms suivant pour utiliser la classe OpenApiInfo :In the Startup class, import the following namespace to use the OpenApiInfo class:

using Microsoft.OpenApi.Models;

À l’aide de la OpenApiInfo classe, modifiez les informations affichées dans l’interface utilisateur :Using the OpenApiInfo class, modify the information displayed in the UI:

// 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 :The Swagger UI displays the version's information:

Interface utilisateur de Swagger avec les informations de version : description, auteur et lien pour en savoir plus

Commentaires XMLXML comments

Vous pouvez activer les commentaires XML en adoptant l’une des approches suivantes :XML comments can be enabled with the following approaches:

  • Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez Modifier <nom_projet>.csproj.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • Ajoutez manuellement les lignes en surbrillance au fichier .csproj :Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • Dans Explorateur de solutions , cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés.Right-click the project in Solution Explorer and select Properties.
  • Cochez la case fichier de documentation XML sous la section sortie de l’onglet générer .Check the XML documentation file box under the Output section of the Build tab.

L’activation de commentaires XML fournit des informations de débogage sur les membres et types publics non documentés.Enabling XML comments provides debug information for undocumented public types and members. Les membres et types non documentés sont indiqués par le message d’avertissement.Undocumented types and members are indicated by the warning message. Par exemple, le message suivant indique une violation du code d’avertissement 1591 :For example, the following message indicates a violation of warning code 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.To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. L’ajout des codes d’avertissement à $(NoWarn); applique aussi les valeurs par défaut C#.Appending the warning codes to $(NoWarn); applies the C# default values too.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
<PropertyGroup>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  <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.To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. Cette approche est utile pour le code qui ne doit pas être exposé via les docs de l’API. Dans l’exemple suivant, le code d’avertissement CS1591 est ignoré pour la Program classe entière.This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning code CS1591 is ignored for the entire Program class. La mise en œuvre de code d’avertissement est restaurée à la fin de la définition de classe.Enforcement of the warning code is restored at the close of the class definition. Spécifier plusieurs codes d’avertissement avec une liste délimitée par des virgules.Specify multiple warning codes with a comma-delimited list.

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.Configure Swagger to use the XML file that's generated with the preceding instructions. Pour les systèmes d’exploitation Linux ou non-Windows, les chemins et les noms de fichiers peuvent respecter la casse.For Linux or non-Windows operating systems, file names and paths can be case-sensitive. Par exemple, un fichier ToDoApi.XML est valide sur Windows, mais pas sur CentOS.For example, a TodoApi.XML file is valid on Windows but not 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);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // 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);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // 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);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // 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.GetEntryAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Dans le code précédent, la réflexion est utilisée pour générer un nom de fichier XML correspondant à celui du projet d’API Web.In the preceding code, Reflection is used to build an XML file name matching that of the web API project. La propriété AppContext.BaseDirectory est utilisée pour construire le chemin du fichier XML.The AppContext.BaseDirectory property is used to construct a path to the XML file. 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.Some Swagger features (for example, schemata of input parameters or HTTP methods and response codes from the respective attributes) work without the use of an XML documentation file. 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.For most features, namely method summaries and the descriptions of parameters and response codes, the use of an XML file is mandatory.

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.Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Ajoutez un <summary> élément au-dessus de l' Delete action :Add a <summary> element above the Delete action:

/// <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 :The Swagger UI displays the inner text of the preceding code's <summary> element:

Interface utilisateur de Swagger affichant le commentaire XML « Deletes a specific TodoItem. »

L’IU est définie par le schéma JSON généré :The UI is driven by the generated JSON schema:

"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 <remarks> élément à la Create documentation de la méthode d’action.Add a <remarks> element to the Create action method documentation. Il complète les informations spécifiées dans l’élément <summary> et fournit une interface utilisateur Swagger plus robuste.It supplements information specified in the <summary> element and provides a more robust Swagger UI. Le contenu de l’élément <remarks> peut être du texte, du code JSON ou du code XML.The <remarks> element content can consist of text, JSON, or 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(typeof(TodoItem), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}
/// <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);
}
/// <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 :Notice the UI enhancements with these additional comments:

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

Annotations de donnéesData annotations

Marquez le modèle avec des attributs, qui se trouvent dans l’espace de noms System. ComponentModel. DataAnnotations , pour aider à piloter les composants de l’interface utilisateur Swagger.Mark the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.

Ajoutez l’attribut [Required] à la propriété Name de la classe TodoItem :Add the [Required] attribute to the Name property of the TodoItem class:

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 change le comportement de l’interface utilisateur et modifie le schéma JSON sous-jacent :The presence of this attribute changes the UI behavior and alters the underlying JSON schema:

"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.Add the [Produces("application/json")] attribute to the API controller. 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 :Its purpose is to declare that the controller's actions support a response content type of application/json:

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

La liste déroulante type de contenu de la réponse sélectionne ce type de contenu comme valeur par défaut pour les actions obtenir du contrôleur :The Response Content Type drop-down selects this content type as the default for the controller's GET actions:

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.As the usage of data annotations in the web API increases, the UI and API help pages become more descriptive and useful.

Décrire des types de réponseDescribe response types

Les développeurs consommant une API web s’intéressent surtout à ce qui est retourné—, en particulier les types de réponse et les codes d’erreur (s’ils ne sont pas standards).Developers consuming a web API are most concerned with what's returned—specifically response types and error codes (if not standard). Les types de réponse et les codes d’erreur sont décrits dans les commentaires XML et les annotations de données.The response types and error codes are denoted in the XML comments and data annotations.

L’action Create retourne un code d’état HTTP 201 en cas de réussite.The Create action returns an HTTP 201 status code on success. Un code d’état HTTP 400 est retourné quand le corps de la demande postée est null.An HTTP 400 status code is returned when the posted request body is null. Sans documentation appropriée dans l’interface utilisateur de Swagger, le consommateur n’a pas connaissance de ces résultats attendus.Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Pour résoudre ce problème, ajoutez les lignes en surbrillance de l’exemple suivant :Fix that problem by adding the highlighted lines in the following example:

/// <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(typeof(TodoItem), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}
/// <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);
}
/// <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 :The Swagger UI now clearly documents the expected HTTP response codes:

Interface utilisateur de Swagger affichant la description de la classe de réponse POST « Returns the newly created Todo item » et « 400 - If the item is null » pour le code d’état et la raison sous Response Messages

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].In ASP.NET Core 2.2 or later, conventions can be used as an alternative to explicitly decorating individual actions with [ProducesResponseType]. Pour plus d'informations, consultez Utiliser les conventions d’API web.For more information, see Utiliser les conventions d’API web.

Pour prendre en charge la [ProducesResponseType] décoration, le package Swashbuckle. AspNetCore. Annotations propose des extensions permettant d’activer et d’enrichir la réponse, le schéma et les métadonnées de paramètre.To support the [ProducesResponseType] decoration, the Swashbuckle.AspNetCore.Annotations package offers extensions to enable and enrich the response, schema, and parameter metadata.

Personnaliser l’interface utilisateurCustomize the UI

L’interface utilisateur par défaut est à la fois fonctionnelle et présente.The default UI is both functional and presentable. Toutefois, les pages de documentation d’API doivent représenter votre marque ou thème.However, API documentation pages should represent your brand or theme. 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.Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

Si vous ciblez le .NET Framework ou .NET Core 1.x, ajoutez le package NuGet Microsoft.AspNetCore.StaticFiles au projet :If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project:

<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.The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.

Activez le middleware de fichiers statiques :Enable Static File Middleware:

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.UseMvc();
}
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 de l’intergiciel (middleware) :To inject additional CSS stylesheets, add them to the project's wwwroot folder and specify the relative path in the middleware options:

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