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.

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

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

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

}

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

app.Run();

Comme meilleure pratique de sécurité sur la limitation de la divulgation d’informations, les interfaces utilisateur OpenAPI (Interface utilisateur Swagger, ReDoc, Scalar) ne doivent être activées que dans les environnements de développement. Par exemple, consultez la configuration swagger OAuth 2.0.

Lancez l’application et accédez à https://localhost:<port>/swagger pour voir l'interface utilisateur Swagger.

Pour lancer automatiquement l’application à l’URL de l’interface utilisateur Swagger en utilisant le profil https de Properties/launchSettings.json:

• Vérifiez que launchBrowser est activé (true).
• Définissez launchUrl sur swagger.

"launchBrowser": true,
"launchUrl": "swagger",

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

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

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

app.Run();

Ouvrez l’application et accédez à https://localhost:<port>/scalar/v1 pour voir l’interface utilisateur Scalar.

Pour lancer l'application automatiquement à l'URL de l'interface utilisateur Scalar à l'aide du profil https de Properties/launchSettings.json :

• Vérifiez que launchBrowser est activé (true).
• Définissez launchUrl sur scalar/v1.

"launchBrowser": true,
"launchUrl": "scalar/v1",

Effectuer une vérification Lint des 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)