Usare documenti openAPI

Usare l'interfaccia utente di Swagger per i test ad hoc locali

Per impostazione predefinita, il Microsoft.AspNetCore.OpenApi pacchetto non viene fornito con il supporto predefinito per la visualizzazione o l'interazione con il documento OpenAPI. Gli strumenti più diffusi per la visualizzazione o l'interazione con il documento OpenAPI includono L'interfaccia utente di Swagger e ReDoc. L'interfaccia utente di Swagger e ReDoc possono essere integrate in un'app in diversi modi. Gli editor come Visual Studio e Visual Studio Code offrono estensioni ed esperienze predefinite per il test su un documento OpenAPI.

Il Swashbuckle.AspNetCore.SwaggerUi pacchetto fornisce un bundle di asset Web dell'interfaccia utente di Swagger da usare nelle app. Questo pacchetto può essere usato per eseguire il rendering di un'interfaccia utente per il documento generato. Per eseguire questa configurazione:

• Installare il pacchetto Swashbuckle.AspNetCore.SwaggerUi.
• Abilitare il middleware swagger-ui con un riferimento alla route OpenAPI registrata in precedenza.

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

Come procedura consigliata per la sicurezza sulla limitazione della divulgazione delle informazioni, le interfacce utente OpenAPI (interfaccia utente di Swagger, ReDoc, Scalar) devono essere abilitate solo negli ambienti di sviluppo. Ad esempio, vedere Configurazione di Swagger OAuth 2.0.

Avvia l'app e accedi a https://localhost:<port>/swagger per visualizzare l'interfaccia utente di Swagger.

Per avviare automaticamente l'app all'URL dell'interfaccia di Swagger utilizzando il profilo https di Properties/launchSettings.json:

• Verificare che launchBrowser sia abilitato (true).
• Imposta launchUrl su swagger.

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

Usare Scalar per la documentazione interattiva dell'API

Scalar è un'interfaccia utente di documento interattiva open source per OpenAPI. Scalare può essere integrato con l'endpoint OpenAPI fornito da ASP.NET Core. Per configurare Scalar, installare il Scalar.AspNetCore pacchetto.

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

Avvia l'app e passa a https://localhost:<port>/scalar per visualizzare l'interfaccia utente Scalar.

Per avviare automaticamente l'app all'URL dell'Interfaccia Utente Scalar usando il profilo https di Properties/launchSettings.json:

• Verificare che launchBrowser sia abilitato (true).
• Imposta launchUrl su scalar.

"launchBrowser": true,
"launchUrl": "scalar",

Documenti OpenAPI generati da Lint con spectrale

Spectral è un linter di documenti OpenAPI open source. È possibile incorporare Spectral nella build di un'applicazione per verificare la qualità dei documenti OpenAPI generati. Installare Spectral in base alle istruzioni di installazione del pacchetto.

Per sfruttare i vantaggi di Spectral per l'esecuzione di documenti OpenAPI in fase di compilazione, installare prima di tutto il pacchetto per abilitare la Microsoft.Extensions.ApiDescription.Server generazione di documenti OpenAPI in fase di compilazione.

Abilitare la generazione di documenti in fase di compilazione impostando le proprietà seguenti nel file dell'app:Enable document generation at build time by setting the following properties in the app's .csproj file":

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

Eseguire dotnet build per generare il documento.

dotnet build

Creare un .spectral.yml file con il contenuto seguente.

extends: ["spectral:oas"]

Eseguire spectral lint nel file generato.

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)

Supporto per l'inserimento IOpenApiDocumentProvider

È possibile inserire IOpenApiDocumentProvider i servizi tramite l'inserimento delle dipendenze per accedere ai documenti OpenAPI a livello di codice, anche all'esterno dei contesti di richiesta HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Registrare il servizio nel contenitore di inserimento delle dipendenze:

builder.Services.AddScoped<DocumentService>();

Ciò consente scenari come la generazione di SDK client, la convalida dei contratti API nei processi in background o l'esportazione di documenti in sistemi esterni.

Il supporto per l'inserimento IOpenApiDocumentProvider è stato introdotto in ASP.NET Core in .NET 10. Per altre informazioni, vedere dotnet/aspnetcore #61463.