Documentation de l’API web ASP.NET Core avec Swagger/OpenAPI

Par Christoph Nienaber et Rico Suter

Swagger (OpenAPI) est une spécification indépendante du langage pour décrire les API REST. Il permet aux ordinateurs et aux humains de comprendre les fonctionnalités d’une API REST sans accès direct au code source. Ses principaux objectifs sont les suivants :

• Réduire la quantité de travail nécessaire pour connecter des services découplés.
• Réduire le temps nécessaire pour documenter avec précision un service.

Les deux principales implémentations OpenAPI pour .NET sont Swashbuckle et NSwag, consultez :

• Bien démarrer avec Swashbuckle
• Bien démarrer avec NSwag

OpenAPI et Swagger

Le projet Swagger a été donné à l’initiative OpenAPI en 2015 et a depuis été appelé OpenAPI. Les deux noms sont utilisés de façon interchangeable. Toutefois, « OpenAPI » fait référence à la spécification. « Swagger » fait référence à la famille de produits open source et commerciaux de SmartBear qui fonctionnent avec la spécification OpenAPI. Les produits open source suivants, tels que OpenAPIGenerator, appartiennent également à la famille Swagger, bien qu’ils ne soient pas publiés par SmartBear.

En résumé :

• OpenAPI est une spécification.
• Swagger est un outil qui utilise la spécification OpenAPI. Par exemple, OpenAPIGenerator et SwaggerUI.

Spécification OpenAPI (openapi.json)

La spécification OpenAPI est un document qui décrit les fonctionnalités de votre API. Le document est basé sur les XML et les annotations d'attribut au sein des contrôleurs et des modèles. Il s’agit de la partie principale du flux OpenAPI et est utilisée pour piloter des outils tels que SwaggerUI. Par défaut, il est nommé openapi.json. Voici un exemple de spécification OpenAPI, réduite pour la concision :

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Interface utilisateur Swagger

L’IU Swagger est une interface utilisateur web qui fournit des informations sur le service, à l’aide de la spécification OpenAPI générée. Swashbuckle et NSwag ont une version incorporée à l’interface utilisateur Swagger pour que vous puissiez l’héberger dans votre application ASP.NET Core à l’aide d’un appel d’inscription d’intergiciel (middleware). L’IU web ressemble à ceci :

Chaque méthode d’action publique dans vos contrôleurs peut être testée à partir de l’IU. Cliquez sur un nom de méthode pour développer la section. Ajoutez tous les paramètres nécessaires, puis cliquez sur L’essayer!.

Notes

La version de l’IU Swagger utilisée pour les captures d’écran est la version 2. Pour obtenir un exemple de la version 3, consultez l’exemple Petstore.

Sécurisation des points de terminaison de l’interface utilisateur Swagger

Appelez MapSwagger().RequireAuthorization pour sécuriser les points de terminaison de l’interface utilisateur Swagger. L’exemple suivant sécurise les points de terminaison Swagger :

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Dans le code précédent, le point de terminaison /weatherforecast n’a pas besoin d’autorisation, contrairement aux points de terminaison Swagger.

La commande Curl suivante transmet un jeton JWT pour tester le point de terminaison de l’interface utilisateur Swagger :

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Pour plus d’informations sur le test avec des jetons JWT, consultez Générer des jetons avec dotnet user-jwts.

Générer un fichier de documentation XML au moment de la compilation.

Consultez GenerateDocumentationFile pour plus d’informations.

Étapes suivantes

• Bien démarrer avec Swashbuckle
• Bien démarrer avec NSwag