Utiliser les documents OpenAPI

Utiliser l’interface utilisateur de Swagger pour les tests ad hoc locaux

Par défaut, le package Microsoft.AspNetCore.OpenApi n’est pas fourni avec la prise en charge intégrée de la visualisation du document OpenAPI ou de l’interaction avec celui-ci. Parmi les outils populaires permettant de visualiser le document OpenAPI ou d’interagir avec celui-ci, citons Swagger UI et ReDoc. Vous pouvez intégrer Swagger UI et ReDoc dans une application de plusieurs façons. Des éditeurs tels que Visual Studio et VS Code proposent des extensions et des expériences intégrées pour effectuer des tests sur un document OpenAPI.

Le package Swashbuckle.AspNetCore.SwaggerUi fournit une offre groupée des ressources web de Swagger UI à utiliser dans les applications. Ce package peut être utilisé pour afficher une interface utilisateur pour le document généré. Pour configurer cela :

• Installez le package Swashbuckle.AspNetCore.SwaggerUi.
• Activez l’intergiciel swagger-ui avec une référence à l’itinéraire OpenAPI inscrit précédemment.
• Pour limiter la divulgation d’informations et les vulnérabilités de sécurité, activez uniquement Swagger UI dans les environnements de développement.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Utiliser Scalar pour la documentation d’API interactive

Scalar est une interface utilisateur de document interactif open source pour OpenAPI. Scalar peut s’intégrer au point de terminaison OpenAPI fourni par ASP.NET Core. Pour configurer Scalar, installez le package Scalar.AspNetCore.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Linting de documents OpenAPI générés avec Spectral

Spectral est un linter de documents OpenAPI open source. Vous pouvez incorporer Spectral dans une build d’application pour vérifier la qualité des documents OpenAPI générés. Installez Spectral en fonction des instructions d’installation du package.

Pour tirer parti de Spectral, installez le package Microsoft.Extensions.ApiDescription.Server pour activer la génération de documents OpenAPI au moment de la build.

Activez la génération de document au moment de la création de la build en définissant les propriétés suivantes dans le fichier .csproj de votre application :

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

Exécutez dotnet build pour générer le document.

dotnet build

Créez un fichier .spectral.yml avec le contenu suivant.

extends: ["spectral:oas"]

Exécutez spectral lint sur le fichier généré.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Pour savoir comment utiliser le document OpenAPI généré dans une API minimale dans .NET 6, 7 ou 8, consultez la Vue d’ensemble de Swagger et NSwag.