Usare documenti openAPI

  • Articolo

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 VS 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.
  • Per limitare la divulgazione e la vulnerabilità della sicurezza delle informazioni, abilitare solo l'interfaccia utente di Swagger negli ambienti di sviluppo.
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();

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

app.MapOpenApi();

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

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

app.Run();

Documenti OpenAPI generati da Lint con spectrale

Spectral è un linter del documento OpenAPI open source. È possibile incorporare spectralmente in una compilazione dell'app per verificare la qualità dei documenti OpenAPI generati. Installare Spectral in base alle istruzioni di installazione del pacchetto.

Per sfruttare i vantaggi di Spectral, installare 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)

Per informazioni su come usare il documento OpenAPI generato in un'API minima in .NET 6, 7 o 8, vedere la panoramica di Swagger e NSwag.