OpenAPI-documenten gebruiken

Swagger UI gebruiken voor lokaal ad-hoc testen

Standaard wordt het Microsoft.AspNetCore.OpenApi-pakket niet geleverd met ingebouwde ondersteuning voor het visualiseren of gebruiken van het OpenAPI-document. Populaire hulpprogramma's voor het visualiseren of gebruiken van het OpenAPI-document zijn Swagger UI- en ReDoc-. Swagger UI en ReDoc kunnen op verschillende manieren in een app worden geïntegreerd. Editors zoals Visual Studio en Visual Studio Code bieden extensies en ingebouwde ervaringen voor het testen op basis van een OpenAPI-document.

Het Swashbuckle.AspNetCore.SwaggerUi-pakket biedt een bundel webassets van de Swagger-gebruikersinterface voor gebruik in apps. Dit pakket kan worden gebruikt om een gebruikersinterface voor het gegenereerde document weer te geven. Ga als volgt te werk om dit te configureren:

• Installeer het Swashbuckle.AspNetCore.SwaggerUi-pakket.
• Schakel de swagger-ui-middleware in met een verwijzing naar de OpenAPI-route die eerder is geregistreerd.

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

Als aanbevolen beveiligingspraktijk voor het beperken van openbaarmaking van informatie , mogen OpenAPI-gebruikersinterfaces (Swagger UI, ReDoc, Scalar) alleen worden ingeschakeld in ontwikkelomgevingen. Zie bijvoorbeeld de configuratie van Swagger OAuth 2.0.

Start de app en navigeer naar https://localhost:<port>/swagger om de Swagger UI te bekijken.

Om de app automatisch te starten op de Swagger UI-URL met behulp van het https profiel van Properties/launchSettings.json:

• Controleer of launchBrowser is ingeschakeld (true).
• Stel de launchUrl in op swagger.

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

Scalar gebruiken voor interactieve API-documentatie

Scalar is een opensource-gebruikersinterface voor interactieve documenten voor OpenAPI. Scalar kan worden geïntegreerd met het OpenAPI-eindpunt dat wordt geleverd door ASP.NET Core. Als u Scalar wilt configureren, installeert u het Scalar.AspNetCore-pakket.

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

Start de app en navigeer naar https://localhost:<port>/scalar/v1 om de scalaire gebruikersinterface weer te geven.

De app automatisch laten starten op de URL van de Scalar UI met behulp van het https profiel van Properties/launchSettings.json.

• Controleer of launchBrowser is ingeschakeld (true).
• Stel de launchUrl in op scalar/v1.

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

Genereer OpenAPI-documenten met Lint en Spectral

Spectral is een open-source OpenAPI-documentlinter. Spectral kan worden opgenomen in een app-build om de kwaliteit van gegenereerde OpenAPI-documenten te controleren. Installeer Spectral volgens de installatie-instructies van het pakket .

Als u wilt profiteren van Spectral voor het linten van OpenAPI-documenten tijdens de build, installeert u eerst het Microsoft.Extensions.ApiDescription.Server pakket om het genereren van openAPI-documenten in buildtijd mogelijk te maken.

Schakel het genereren van documenten tijdens de build in door de volgende eigenschappen in te stellen in het .csproj-bestand van de app":

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

Voer dotnet build uit om het document te genereren.

dotnet build

Maak een .spectral.yml-bestand met de volgende inhoud.

extends: ["spectral:oas"]

Voer spectral lint uit op het gegenereerde bestand.

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)

Ondersteuning voor injecteren IOpenApiDocumentProvider

U kunt Microsoft.AspNetCore.OpenApi.Services.IOpenApiDocumentProvider in uw services injecteren via dependency injection om programmeerbaar toegang te krijgen tot OpenAPI-documenten, zelfs buiten HTTP-aanvraagcontexten.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

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

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

Registreer de service in uw DI-container:

builder.Services.AddScoped<DocumentService>();

Dit maakt scenario's mogelijk, zoals het genereren van client-SDK's, het valideren van API-contracten in achtergrondprocessen of het exporteren van documenten naar externe systemen.

Ondersteuning voor injecteren IOpenApiDocumentProvider is geïntroduceerd in ASP.NET Core in .NET 10. Zie dotnet/aspnetcore #61463 voor meer informatie.

Zie het overzicht van de Swagger en NSwag voor meer informatie over het gebruik van het gegenereerde OpenAPI-document in een minimale API in .NET 6, 7 of 8.

Swagger UI gebruiken voor lokaal ad-hoc testen

Standaard wordt het Microsoft.AspNetCore.OpenApi-pakket niet geleverd met ingebouwde ondersteuning voor het visualiseren of gebruiken van het OpenAPI-document. Populaire hulpprogramma's voor het visualiseren of gebruiken van het OpenAPI-document zijn Swagger UI- en ReDoc-. Swagger UI en ReDoc kunnen op verschillende manieren in een app worden geïntegreerd. Editors zoals Visual Studio en VS Code bieden extensies en ingebouwde ervaringen voor het testen op basis van een OpenAPI-document.

Het Swashbuckle.AspNetCore.SwaggerUi-pakket biedt een bundel webassets van de Swagger-gebruikersinterface voor gebruik in apps. Dit pakket kan worden gebruikt om een gebruikersinterface voor het gegenereerde document weer te geven. Ga als volgt te werk om dit te configureren:

• Installeer het Swashbuckle.AspNetCore.SwaggerUi-pakket.
• Schakel de swagger-ui-middleware in met een verwijzing naar de OpenAPI-route die eerder is geregistreerd.

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

Als aanbevolen beveiligingspraktijk voor het beperken van openbaarmaking van informatie , mogen OpenAPI-gebruikersinterfaces (Swagger UI, ReDoc, Scalar) alleen worden ingeschakeld in ontwikkelomgevingen. Zie bijvoorbeeld de configuratie van Swagger OAuth 2.0.

Start de app en navigeer naar https://localhost:<port>/swagger om de Swagger UI te bekijken.

Om de app automatisch te starten op de Swagger UI-URL met behulp van het https profiel van Properties/launchSettings.json:

• Controleer of launchBrowser is ingeschakeld (true).
• Stel de launchUrl in op swagger.

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

Scalar gebruiken voor interactieve API-documentatie

Scalar is een opensource-gebruikersinterface voor interactieve documenten voor OpenAPI. Scalar kan worden geïntegreerd met het OpenAPI-eindpunt dat wordt geleverd door ASP.NET Core. Als u Scalar wilt configureren, installeert u het Scalar.AspNetCore-pakket.

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

Start de app en navigeer naar https://localhost:<port>/scalar/v1 om de scalaire gebruikersinterface weer te geven.

De app automatisch laten starten op de URL van de Scalar UI met behulp van het https profiel van Properties/launchSettings.json.

• Controleer of launchBrowser is ingeschakeld (true).
• Stel de launchUrl in op scalar/v1.

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

Genereer OpenAPI-documenten met Lint en Spectral

Spectral is een open-source OpenAPI-documentlinter. Spectral kan worden opgenomen in een app-build om de kwaliteit van gegenereerde OpenAPI-documenten te controleren. Installeer Spectral volgens de installatie-instructies van het pakket .

Als u wilt profiteren van Spectral, installeert u het Microsoft.Extensions.ApiDescription.Server-pakket om het genereren van openAPI-documenten in buildtijd mogelijk te maken.

Schakel het genereren van documenten tijdens de build in door de volgende eigenschappen in te stellen in het .csproj-bestand van de app":

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

Voer dotnet build uit om het document te genereren.

dotnet build

Maak een .spectral.yml-bestand met de volgende inhoud.

extends: ["spectral:oas"]

Voer spectral lint uit op het gegenereerde bestand.

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)