Bien démarrer avec NSwag et ASP.NET Core

Par Christoph Nienaber, Rico Suter et Dave Brock

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

NSwag offre les avantages suivants :

• La possibilité d’utiliser l’interface utilisateur de Swagger et le générateur Swagger.
• Fonctionnalités de génération de code flexibles.

Avec NSwag, vous n’avez pas besoin d’une API existante, vous pouvez utiliser des API de tiers qui intègrent Swagger et génèrent une implémentation du client. NSwag vous permet d’accélérer le cycle de développement et de vous adapter facilement aux modifications de l’API.

Installation de package

Installez NSwag sur :

• Générer la spécification Swagger pour l’API web implémentée.
• Utiliser l’interface utilisateur Swagger pour parcourir et tester l’API web.
• Servez le Redoc pour ajouter la documentation de l’API pour l’API web.

Pour utiliser le middleware NSwag avec ASP.NET Core, installez le package NuGet NSwag.AspNetCore. Ce package contient le middleware nécessaire pour générer et utiliser la spécification Swagger, l’interface utilisateur Swagger (v2 et v3) et l’IU ReDoc.

Vous pouvez installer le package NuGet NSwag avec l’une des méthodes suivantes :

Visual Studio

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

  • Accédez à Affichage>Autres fenêtres>Console du Gestionnaire de package.

  • Accédez au répertoire où se trouve le fichier NSwagSample.csproj.

  • Exécutez la commande suivante :

    Install-Package NSwag.AspNetCore
    

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

  • Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions>Gérer les packages NuGet.
  • Affectez la valeur « nuget.org » à Source du package.
  • Entrez « NSwag.AspNetCore » dans la zone de recherche.
  • Sélectionnez le package « NSwag.AspNetCore » sous l’onglet Parcourir et cliquez sur Installer.

Visual Studio pour Mac

• Cliquez avec le bouton droit sur le dossier Packages dans Panneau Solutions>Ajouter des packages.
• Dans la fenêtre Ajouter des packages, sélectionnez « nuget.org » dans la liste déroulante Source.
• Entrez « NSwag.AspNetCore » dans la zone de recherche.
• Sélectionnez le package « NSwag.AspNetCore » dans le volet de résultats, puis cliquez sur Ajouter un package.

Visual Studio Code

Exécutez la commande suivante à partir du Terminal intégré :

dotnet add NSwagSample.csproj package NSwag.AspNetCore

CLI .NET Core

Exécutez la commande suivante:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Ajouter et configurer l’intergiciel (middleware) Swagger

Ajoutez et configurez Swagger dans votre application ASP.NET Core en exécutant les étapes suivantes :

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();

• Activez l’intergiciel pour traiter la spécification OpenApi générée, l’interface utilisateur Swagger et l’interface utilisateur Redoc, également dans Program.cs :

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi();
}

• Lancez l’application. Accédez à :
  • http://localhost:<port>/swagger pour voir l’IU de Swagger.
  • http://localhost:<port>/swagger/v1/swagger.json pour voir la spécification Swagger.

Génération de code

Vous pouvez tirer parti des fonctionnalités de génération de code de NSwag en choisissant l’une des options suivantes :

• NSwagStudio : une application de bureau Windows pour générer du code client d’API en C# ou TypeScript pour une API.
• Les packages NuGet NSwag.CodeGeneration.CSharp ou NSwag.CodeGeneration.TypeScript pour générer du code dans votre projet.
• NSwag à partir de la ligne de commande.
• Le package NuGet NSwag.MSBuild.
• Le service connecté Unchase OpenAPI (Swagger) : un service connecté Visual Studio qui permet de générer du code client d’API en C# ou TypeScript. Génère également des contrôleurs C# pour les services OpenAPI avec NSwag.

Générer du code avec NSwagStudio

• Installez NSwagStudio en suivant les instructions fournies dans le référentiel GitHub de NSwagStudio. Sur la page de publication NSwag, vous pouvez télécharger une version xcopy qui peut être démarrée sans privilèges d’installation et d’administrateur.
• Lancez NSwagStudio et entrez l’URL du fichier swagger.json dans la zone de texte Swagger Specification URL (URL de spécification Swagger). Par exemple, http://localhost:5232/swagger/v1/swagger.json.
• Cliquez sur le bouton Créer une copie locale pour générer une représentation JSON de votre spécification Swagger.

• Dans la zone Sorties, cliquez sur la case Client CSharp. Selon votre projet, vous pouvez également choisir TypeScript Client ou CSharp Web API Controller. Si vous sélectionnez CSharp Web API Controller, une spécification de service reconstruit le service, agissant comme une génération inverse.
• Cliquez sur Générer des sorties pour produire une implémentation client C# complète du projet TodoApi.NSwag. Pour afficher le code client généré, cliquez sur l’onglet CSharp Client :

namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // code omitted for brevity

Conseil

Le code client C# est généré en fonction des sélections dans l’onglet Paramètres. Modifiez les paramètres pour effectuer des tâches telles que le renommage de l’espace de noms par défaut et la génération de méthode synchrone.

• Copiez le code C# généré dans un fichier dans le projet client qui utilisera l’API.
• Démarrez l’utilisation de l’API web :

var todoClient = new TodoClient(new HttpClient());

// Gets all to-dos from the API
var allTodos = await todoClient.GetAsync();

// Create a new TodoItem, and save it via the API.
await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Personnaliser la documentation sur l’API

OpenApi fournit des options pour documenter le modèle objet afin de faciliter la consommation de l’API web.

Informations sur l’API et description

Dans Program.cs, mettez à jour AddOpenApiDocument pour configurer les informations de document de l’API web et inclure plus d’informations telles que l’auteur, la licence et la description. Importez d’abord l’espace de noms NSwag pour utiliser les classes OpenApi.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

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

L’IU Swagger affiche les informations de la version :

commentaires XML

Pour activer les commentaires XML, procédez comme suit :

Visual Studio

• Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Edit <project_name>.csproj.
• Ajoutez manuellement les lignes en évidence au fichier .csproj :

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio pour Mac

• Dans le Panneau Solutions, appuyez sur contrôle et cliquez sur le nom du projet. Accédez à Outils>Modifier le fichier.
• Ajoutez manuellement les lignes en évidence au fichier .csproj :

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Ajoutez manuellement les lignes en évidence au fichier .csproj :

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

CLI .NET Core

Ajoutez manuellement les lignes en évidence au fichier .csproj :

<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 'TodoContext'

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 de la classe TodoContext. 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 NSwagSample.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

Annotations de données

Marquez le modèle avec des attributs, qui se trouvent dans l’espace de noms System.ComponentModel.DataAnnotations, pour piloter les composants de l’interface utilisateur de Swagger.

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

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

namespace NSwagSample.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 change le comportement de l’interface utilisateur et modifie le schéma JSON sous-jacent :

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

À 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 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 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é lorsque le corps de la demande publié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 Swagger documente désormais clairement les codes de réponse HTTP attendus (et les commentaires XML sont également affichés) :

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.

Redoc

Redoc est une alternative à l’interface utilisateur Swagger. Elle est similaire, car elle fournit également une page de documentation pour l’API web à l’aide de la spécification OpenAPI. La différence est que l’interface utilisateur Redoc est plus axée sur la documentation et ne fournit pas d’interface utilisateur interactive pour tester l’API.

Pour activer Redoc, ajoutez son intergiciel à Program.cs :

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi();
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Exécutez l’application et accédez à http://localhost:<port>/redoc pour afficher l’interface utilisateur Redoc :