Generera OpenAPI-dokument

Microsoft.AspNetCore.OpenApi-paketet ger inbyggt stöd för OpenAPI-dokumentgenerering i ASP.NET Core. Paketet innehåller följande funktioner:

• Stöd för att generera OpenAPI-dokument under körningen och ge åtkomst till dem via en slutpunkt i applikationen.
• Stöd för "transformerings-API:er" som gör det möjligt att ändra det genererade dokumentet.
• Stöd för att generera flera OpenAPI-dokument från en enda app.
• Utnyttjar JSON-schemastöd som tillhandahålls av System.Text.Json.
• Är kompatibel med inbyggd AoT.

Paketinstallation

Installera Microsoft.AspNetCore.OpenApi-paketet:

Visual Studio

Kör följande kommando från Package Manager-konsolen:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Kör följande kommando:

dotnet add package Microsoft.AspNetCore.OpenApi

Konfigurera OpenAPI-dokumentgenerering

Följande kod:

• Lägger till OpenAPI-tjänster.
• Aktiverar slutpunkten för att visa OpenAPI-dokumentet i JSON-format.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Starta appen och gå till https://localhost:<port>/openapi/v1.json för att visa det genererade OpenAPI-dokumentet.

Alternativ för att anpassa OpenAPI-dokumentgenerering

Följande avsnitt visar hur du anpassar OpenAPI-dokumentgenerering.

Anpassa OpenAPI-dokumentnamnet

Varje OpenAPI-dokument i en app har ett unikt namn. Standarddokumentnamnet som är registrerat är v1.

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

Dokumentnamnet kan ändras genom att skicka namnet som en parameter till AddOpenApi-anropet.

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

Dokumentnamnet visas på flera platser i OpenAPI-implementeringen.

När du hämtar det genererade OpenAPI-dokumentet anges dokumentnamnet som argumentet documentName parameter i begäran. Följande begäranden behandlar dokumenten v1 och internal.

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

Anpassa OpenAPI-versionen av ett genererat dokument

Som standard skapar OpenAPI-dokumentgenerering ett dokument som är kompatibelt med v3.0 i OpenAPI-specifikationen. Följande kod visar hur du ändrar standardversionen av OpenAPI-dokumentet:

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

Anpassa OpenAPI-slutpunktsvägen

Som standard exponerar OpenAPI-slutpunkten som registrerats via ett anrop till MapOpenApi dokumentet på /openapi/{documentName}.json slutpunkten. Följande kod visar hur du anpassar den väg där OpenAPI-dokumentet är registrerat:

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

Det är möjligt, men rekommenderas inte, att ta bort documentName vägparametern från slutpunktsvägen. När documentName vägparametern tas bort från slutpunktsrutten försöker ramverket lösa ut dokumentnamnet från en frågeparameter. Om du inte anger documentName i antingen vägen eller frågan kan det leda till oväntat beteende.

Anpassa OpenAPI-slutpunkten

Eftersom OpenAPI-dokumentet hanteras via en slutpunkt för routningshanterare är alla anpassningar som är tillgängliga för minimala standardslutpunkter tillgängliga för OpenAPI-slutpunkten.

Begränsa OpenAPI-dokumentåtkomst till behöriga användare

OpenAPI-slutpunkten aktiverar inte några auktoriseringskontroller som standard. Auktoriseringskontroller kan dock tillämpas på OpenAPI-dokumentet. I följande kod är åtkomsten till OpenAPI-dokumentet begränsad till dem med den tester rollen:

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

Cachegenererat OpenAPI-dokument

OpenAPI-dokumentet återskapas varje gång en begäran till OpenAPI-slutpunkten skickas. Regenerering gör det möjligt för transformatorer att införliva dynamiskt programtillstånd i sin drift. Till exempel återskapa en begäran med information om HTTP-kontexten. När det är tillämpligt kan OpenAPI-dokumentet cachelagras för att undvika att köra pipelinen för dokumentgenerering på varje HTTP-begäran.

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

app.MapOpenApi()
    .CacheOutput();

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

app.Run();

Generera OpenAPI-dokument vid byggtid

I vanliga webbprogram genereras OpenAPI-dokument vid körning och hanteras via en HTTP-begäran till programservern.

I vissa scenarier är det bra att generera OpenAPI-dokumentet under programmets byggsteg. Dessa scenarier omfattar:

• Generera OpenAPI-dokumentation som har checkats in i källkontrollen.
• Generera OpenAPI-dokumentation som används för specifikationsbaserad integreringstestning.
• Generera OpenAPI-dokumentation som hanteras statiskt från webbservern.

Om du vill lägga till stöd för att generera OpenAPI-dokument vid bygget installerar du Microsoft.Extensions.ApiDescription.Server-paketet:

Visual Studio

Kör följande kommando från Package Manager-konsolen:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

Kör följande kommando i katalogen som innehåller projektfilen:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Vid installationen genererar det här paketet automatiskt de Öppna API-dokument som är associerade med programmet under bygget och fyller i dem i programmets utdatakatalog.

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

Anpassa generering av byggtidsdokument

Ändra utdatakatalogen för den genererade Öppna API-filen

Som standard skickas det genererade OpenAPI-dokumentet till programmets utdatakatalog. För att ändra platsen för den genererade filen anger du målsökvägen i egenskapen OpenApiDocumentsDirectory.

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

Värdet för OpenApiDocumentsDirectory bestäms i förhållande till projektfilen. Genom att använda värdet ./ ovan kommer OpenAPI-dokumentet att placeras i samma katalog som projektfilen.

Ändra namnet på utdatafilen

Som standard har det genererade OpenAPI-dokumentet samma namn som programmets projektfil. Om du vill ändra namnet på den utelämnade filen anger du argumentet --file-name i egenskapen OpenApiGenerateDocumentsOptions.

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

Välja det OpenAPI-dokument som ska genereras

Vissa program kan konfigureras för att generera flera OpenAPI-dokument, för olika versioner av ett API eller för att skilja mellan offentliga och interna API:er. Som standard genererar byggtidsdokumentgeneratorn filer för alla dokument som har konfigurerats i ett program. Om du bara vill generera ett enda dokumentnamn anger du argumentet --document-name i egenskapen OpenApiGenerateDocumentsOptions.

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

Anpassa körningsbeteende under generering av byggtidsdokument

OpenAPI-funktioner för dokumentgenerering vid byggtid genom att starta applikationens startpunkt med en mockserver-implementation. En falsk server krävs för att skapa korrekta OpenAPI-dokument eftersom all information i OpenAPI-dokumentet inte kan analyseras statiskt. Eftersom appinmatningspunkten anropas anropas all logik i appstarten. Detta inkluderar kod som matar in tjänster i DI-containern eller läser från konfigurationen. I vissa scenarier är det nödvändigt att begränsa de kodsökvägar som ska köras när apparnas startpunkt anropas från dokumentgenerering vid byggtid. Dessa scenarier omfattar:

• Läser inte från vissa konfigurationssträngar.
• Registrerar inte databasrelaterade tjänster.

För att begränsa dessa kodvägar från att anropas av byggtidsgenereringspipelinens kan de villkoras bakom en kontroll av inmatningssamlingen.

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 Lägger till vanliga .NET Aspire tjänster som tjänstidentifiering, motståndskraft, hälsokontroller och OpenTelemetry.

Trimning och intern AOT

OpenAPI i ASP.NET Core stöder trimning och intern AOT. Följande steg skapar och publicerar en OpenAPI-app med trimning och inbyggd AOT:

Skapa ett nytt ASP.NET Core Web API-projekt (native AOT).

dotnet new webapiaot

Lägg till Paketet Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

Uppdatera Program.cs för att aktivera generering av OpenAPI-dokument.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Publicera appen.

dotnet publish