OpenAPI-documenten genereren

Het Microsoft.AspNetCore.OpenApi-pakket biedt ingebouwde ondersteuning voor het genereren van OpenAPI-documenten in ASP.NET Core. Het pakket biedt de volgende functies:

• Ondersteuning voor het genereren van OpenAPI-documenten tijdens runtime en het openen ervan via een eindpunt in de toepassing.
• Ondersteuning voor 'transformer'-API's waarmee het gegenereerde document kan worden gewijzigd.
• Ondersteuning voor het genereren van meerdere OpenAPI-documenten vanuit één app.
• Maakt gebruik van JSON-schemaondersteuning die wordt geboden door System.Text.Json.
• Is compatibel met systeemeigen AoT.

Pakketinstallatie

Installeer het Microsoft.AspNetCore.OpenApi-pakket:

Visual Studio

Voer de volgende opdracht uit vanuit de Package Manager Console:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Voer de volgende opdracht uit:

dotnet add package Microsoft.AspNetCore.OpenApi

Het genereren van OpenAPI-documenten configureren

De volgende code:

• Hiermee worden OpenAPI-services toegevoegd met behulp van de extensiemethode AddOpenApi in de serviceverzameling van de app-builder.
• Hiermee wordt een eindpunt toegewezen voor het weergeven van het OpenAPI-document in JSON-indeling met de extensiemethode MapOpenApi in de app.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Start de app en navigeer naar https://localhost:<port>/openapi/v1.json om het gegenereerde OpenAPI-document weer te geven.

Opties voor het aanpassen van het genereren van OpenAPI-documenten

In de volgende secties ziet u hoe u het genereren van OpenAPI-documenten kunt aanpassen.

De naam van het OpenAPI-document aanpassen

Elk OpenAPI-document in een app heeft een unieke naam. De standaarddocumentnaam die is geregistreerd, is v1.

builder.Services.AddOpenApi(); // Document name is v1

De documentnaam kan worden gewijzigd door de naam als parameter door te geven aan de AddOpenApi aanroep.

builder.Services.AddOpenApi("internal"); // Document name is internal

De documentnaam wordt op verschillende plaatsen in de OpenAPI-implementatie weergegeven.

Bij het ophalen van het gegenereerde OpenAPI-document wordt de documentnaam opgegeven als de parameter documentName in het verzoek. De volgende verzoeken lossen de v1- en internal-documenten op.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

De OpenAPI-versie van een gegenereerd document aanpassen

Standaard maakt het genereren van OpenAPI-documenten een document dat compatibel is met v3.0 van de OpenAPI-specificatie. De volgende code laat zien hoe u de standaardversie van het OpenAPI-document wijzigt:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

De Route van het OpenAPI-eindpunt aanpassen

Standaard maakt het OpenAPI-eindpunt dat is geregistreerd via een aanroep naar MapOpenApi het document toegankelijk op het /openapi/{documentName}.json-eindpunt. De volgende code laat zien hoe u de route kunt aanpassen waarop het OpenAPI-document is geregistreerd:

app.MapOpenApi("/openapi/{documentName}/openapi.json");

Het is mogelijk, maar niet aanbevolen, om de documentName routeparameter uit de eindpuntroute te verwijderen. Wanneer de documentName routeparameter wordt verwijderd uit de eindpuntroute, probeert het framework de documentnaam op te lossen uit de queryparameter. Het niet opgeven van de documentName in de route of query kan leiden tot onverwacht gedrag.

Het OpenAPI-eindpunt aanpassen

Omdat het OpenAPI-document wordt geleverd via een routehandlereindpunt, is elke aanpassing die beschikbaar is voor standaard minimale eindpunten beschikbaar voor het OpenAPI-eindpunt.

OpenAPI-documenttoegang beperken tot geautoriseerde gebruikers

Het OpenAPI-eindpunt schakelt standaard geen autorisatiecontroles in. Autorisatiecontroles kunnen echter worden toegepast op het OpenAPI-document. In de volgende code is de toegang tot het OpenAPI-document beperkt tot personen met de rol tester:

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.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

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

app.Run();

Door cache gegenereerd OpenAPI-document

Het OpenAPI-document wordt telkens opnieuw gegenereerd wanneer een aanvraag naar het OpenAPI-eindpunt wordt verzonden. Met regeneratie kunnen transformatoren dynamische toepassingsstatus opnemen in hun werking. Bijvoorbeeld het opnieuw genereren van een aanvraag met details van de HTTP-context. Indien van toepassing kan het OpenAPI-document in de cache worden opgeslagen om te voorkomen dat de pijplijn voor het genereren van documenten op elke HTTP-aanvraag wordt uitgevoerd.

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

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

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

app.Run();

Meerdere OpenAPI-documenten genereren

In sommige scenario's is het handig om meerdere OpenAPI-documenten te genereren met verschillende inhoud van één ASP.NET Core API-app. Deze scenario's omvatten:

• OpenAPI-documentatie genereren voor verschillende doelgroepen, zoals openbare en interne API's.
• OpenAPI-documentatie genereren voor verschillende versies van een API.
• OpenAPI-documentatie genereren voor verschillende onderdelen van een toepassing, zoals een front-end- en back-end-API.

Als u meerdere OpenAPI-documenten wilt genereren, roept u de AddOpenApi-extensiemethode eenmaal aan voor elk document, waarbij u telkens een andere documentnaam opgeeft in de eerste parameter.

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Elke aanroep van AddOpenApi kan een eigen set opties opgeven, zodat u dezelfde of verschillende aanpassingen voor elk OpenAPI-document kunt gebruiken.

Het framework maakt gebruik van de ShouldInclude delegatiemethode van OpenApiOptions om te bepalen welke eindpunten in elk document moeten worden opgenomen.

Voor elk document wordt de ShouldInclude gedelegeerde methode aangeroepen voor elk eindpunt in de toepassing, waarbij het ApiDescription-object voor het eindpunt wordt doorgegeven. De methode retourneert een Booleaanse waarde die aangeeft of het eindpunt in het document moet worden opgenomen. Het ApiDescription-object bevat informatie over het eindpunt, zoals de HTTP-methode, route en antwoordtypen, evenals metagegevens die zijn gekoppeld aan het eindpunt via kenmerken of extensiemethoden.

De standaard implementatie van deze gemachtigde maakt gebruik van het GroupName veld van ApiDescription, dat is ingesteld op een eindpunt met behulp van de WithGroupName extensiemethode of het kenmerk EndpointGroupNameAttribute, om te bepalen welke eindpunten in het document moeten worden opgenomen. Elk eindpunt waaraan geen groepsnaam is toegewezen, bevat alle OpenAPI-documenten.

    // Include endpoints without a group name or with a group name that matches the document name
    ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName;    

U kunt de ShouldInclude delegeringsmethode aanpassen om eindpunten op te nemen of uit te sluiten op basis van de criteria die u kiest.

OpenAPI-documenten genereren tijdens de build

In typische webtoepassingen worden OpenAPI-documenten gegenereerd tijdens runtime en geleverd via een HTTP-aanvraag naar de toepassingsserver.

In sommige scenario's is het handig om het OpenAPI-document te genereren tijdens de buildstap van de toepassing. Deze scenario's omvatten:

• OpenAPI-documentatie genereren die wordt opgeslagen in versiebeheer.
• OpenAPI-documentatie genereren die wordt gebruikt voor op spec gebaseerde integratietests.
• OpenAPI-documentatie genereren die statisch wordt geleverd vanaf de webserver.

Als u ondersteuning wilt toevoegen voor het genereren van OpenAPI-documenten tijdens de build, installeert u het Microsoft.Extensions.ApiDescription.Server-pakket:

Visual Studio

Voer de volgende opdracht uit vanuit de Package Manager Console:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

Voer de volgende opdracht uit in de map die het projectbestand bevat:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Bij de installatie genereert dit pakket automatisch de Open API-documenten die tijdens de build aan de toepassing zijn gekoppeld en vullen deze in de uitvoermap van de toepassing.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Het aanpassen van de generatie van build-time documenten

De uitvoermap van het gegenereerde Open API-bestand wijzigen

Standaard wordt het gegenereerde OpenAPI-document verzonden naar de uitvoermap van de toepassing. Als u de locatie van het verzonden bestand wilt wijzigen, stelt u het doelpad in de eigenschap OpenApiDocumentsDirectory in.

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
</PropertyGroup>

De waarde van OpenApiDocumentsDirectory wordt bepaald ten opzichte van het projectbestand. Als u de bovenstaande . waarde gebruikt, wordt het OpenAPI-document verzonden in dezelfde map als het projectbestand.

De naam van het uitvoerbestand wijzigen

Het gegenereerde OpenAPI-document heeft standaard dezelfde naam als het projectbestand van de toepassing. Als u de naam van het verzonden bestand wilt wijzigen, stelt u het argument --file-name in de eigenschap OpenApiGenerateDocumentsOptions in.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Het OpenAPI-document selecteren dat moet worden gegenereerd

Sommige toepassingen kunnen worden geconfigureerd om meerdere OpenAPI-documenten te verzenden, voor verschillende versies van een API of om onderscheid te maken tussen openbare en interne API's. Standaard verzendt de build-time documentgenerator bestanden voor alle documenten die zijn geconfigureerd in een toepassing. Als u slechts één documentnaam wilt verzenden, stelt u het argument --document-name in de eigenschap OpenApiGenerateDocumentsOptions in.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Runtimegedrag aanpassen tijdens het genereren van build-time-documenten

Functies voor het genereren van OpenAPI-documenten tijdens de build-tijd door het toegangspunt van de app te starten met een mockserver-implementatie. Er is een mockserver vereist om nauwkeurige OpenAPI-documenten te produceren, omdat alle informatie in het OpenAPI-document niet statisch kan worden geanalyseerd. Omdat het toegangspunt voor apps wordt aangeroepen, wordt elke logica in het opstarten van de apps aangeroepen. Dit omvat code die services injecteert in de DI-container of uit de configuratie leest. In sommige scenario's is het nodig om de codepaden te beperken die worden uitgevoerd wanneer het toegangspunt van apps wordt aangeroepen tijdens de build-time-documentgeneratie. Deze scenario's omvatten:

• Niet lezen uit bepaalde configuratiereeksen.
• Databasegerelateerde services worden niet geregistreerd.

Om te voorkomen dat deze codepaden worden aangeroepen door de build-time generatiepijplijn, kunnen ze worden geconditioneerd op basis van een controle van de invoerassembly.

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
    builder.AddServiceDefaults();
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults voegt algemene .NET Aspire-services toe, zoals servicedetectie, tolerantie, statuscontroles en OpenTelemetry.

Bijsnijden en systeemeigen AOT

OpenAPI in ASP.NET Core biedt ondersteuning voor bijsnijden en systeemeigen AOT. Met de volgende stappen maakt en publiceert u een OpenAPI-app met bijsnijden en systeemeigen AOT:

Maak een nieuw ASP.NET Core Web API-project (Native AOT).

dotnet new webapiaot

Voeg het Microsoft.AspNetCore.OpenAPI-pakket toe.

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

Werk Program.cs bij om het genereren van OpenAPI-documenten in te schakelen.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Publiceer de app.

dotnet publish