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

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

Swashbuckle compte 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. Il est généralement associé à l’intergiciel de point de terminaison Swagger pour exposer automatiquement Swagger JSON.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. Elle interprète Swagger JSON afin de générer une expérience complète et personnalisable pour décrire la fonctionnalité de l’API web.It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Il inclut des ateliers de test intégrés 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édez à Affichage > Autres fenêtres > Console du Gestionnaire de package.Go 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
      
  • À 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 l’Explorateur de solutions > Gérer les packages NuGet.Right-click the project in Solution Explorer > Manage NuGet Packages
    • Affectez la valeur « nuget.org » à Source du package.Set the Package source to "nuget.org"
    • Entrez « Swashbuckle.AspNetCore » dans la zone de recherche.Enter "Swashbuckle.AspNetCore" in the search box
    • Sélectionnez le package « Swashbuckle.AspNetCore » sous l’onglet Parcourir et cliquez sur Installer.Select the "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(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}
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 Info { Title = "My API", Version = "v1" });
    });
}

Importez les espaces de noms suivants à utiliser dans la classe Info :Import the following namespace to use the Info class:

using Swashbuckle.AspNetCore.Swagger;

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();
}

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 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.

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 illustré dans la spécification Swagger (swagger.json).The generated document describing the endpoints appears as shown in Swagger specification (swagger.json).

L’IU 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’IU 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 à la place 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.

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.

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 licence et la description :The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        },
        License = new License
        {
            Name = "Use under LICX",
            Url = "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>
  • Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez Propriétés.Right-click the project in Solution Explorer and select Properties.
  • Cochez la case Fichier de documentation XML dans la section Sortie sous 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é par le biais des documentations des API. Dans l’exemple suivant, le code d’avertissement CS1591 est ignoré pour toute la classe Program.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 pour utiliser le fichier XML généré.Configure Swagger to use the generated XML file. 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.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "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 Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "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 Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "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.

Quand vous ajoutez des commentaires avec trois barres obliques à une action, la description est ajoutée à l’en-tête de section dans l’IU Swagger.Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Ajoutez un élément <summary> au dessus de l’action Delete :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 élément <remarks> à la documentation de la méthode de l’action Create.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 IU 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), 201)]
[ProducesResponseType(400)]
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(201)]
[ProducesResponseType(400)]
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

Décorez le modèle avec des attributs, présents dans l’espace de noms System.ComponentModel.DataAnnotations, pour gérer les composants de l’IU Swagger.Decorate 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;

La zone de liste déroulante Response Content Type permet de sélectionner ce type de contenu comme valeur par défaut pour les actions GET 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), 201)]
[ProducesResponseType(400)]
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(201)]
[ProducesResponseType(400)]
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.

Personnaliser l’IUCustomize the UI

L’IU de stock est fonctionnelle et conviviale.The stock 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();
}

Faites l’acquisition du contenu du dossier dist à partir du dépôt GitHub de l’interface utilisateur de Swagger.Acquire the contents of the dist folder from the Swagger UI GitHub repository. Ce dossier contient les ressources nécessaires pour la page de l’interface utilisateur de Swagger.This folder contains the necessary assets for the Swagger UI page.

Créez un dossier wwwroot/swagger/ui et copiez dedans le contenu du dossier dist.Create a wwwroot/swagger/ui folder, and copy into it the contents of the dist folder.

Créez un fichier custom.css dans wwwroot/swagger/ui avec le code CSS suivant pour personnaliser l’en-tête de page :Create a custom.css file, in wwwroot/swagger/ui, with the following CSS to customize the page header:

.swagger-ui .topbar {
    background-color: #000;
    border-bottom: 3px solid #547f00;
}

Référencez custom.css dans le fichier index.html, à la suite de n’importe quel autre fichier CSS :Reference custom.css in the index.html file, after any other CSS files:

<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">

Accédez à la page index.html à l’adresse http://localhost:<port>/swagger/ui/index.html.Browse to the index.html page at http://localhost:<port>/swagger/ui/index.html. Entrez http://localhost:<port>/swagger/v1/swagger.json dans la zone de texte de l’en-tête, puis cliquez sur le bouton Explorer.Enter http://localhost:<port>/swagger/v1/swagger.json in the header's textbox, and click the Explore button. La page résultante ressemble à ceci :The resulting page looks as follows:

Interface utilisateur de Swagger avec titre d’en-tête personnalisé

Vous pouvez faire encore beaucoup avec cette page.There's much more you can do with the page. Pour découvrir toutes les fonctionnalités pour les ressources d’interface utilisateur, accédez au dépôt GitHub de l’interface utilisateur de Swagger.See the full capabilities for the UI resources at the Swagger UI GitHub repository.