Generování dokumentů OpenAPI

Balíček Microsoft.AspNetCore.OpenApi poskytuje integrovanou podporu generování dokumentů OpenAPI v ASP.NET Core. Balíček obsahuje následující funkce:

• Podpora generování dokumentů OpenAPI za běhu a přístup k nim prostřednictvím koncového bodu v aplikaci
• Podpora rozhraní API transformátoru, která umožňují upravovat vygenerovaný dokument.
• Podpora generování více dokumentů OpenAPI z jedné aplikace
• Využívá podporu schématu JSON, kterou System.Text.Jsonposkytuje .
• Je kompatibilní s nativní AoT.

Instalace balíčku

Microsoft.AspNetCore.OpenApi Nainstalujte balíček:

Visual Studio

V konzole Správce balíčků spusťte následující příkaz:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Spusťte následující příkaz:

dotnet add package Microsoft.AspNetCore.OpenApi

Konfigurace generování dokumentů OpenAPI

Následující kód:

• Přidá služby OpenAPI.
• Povolí koncový bod pro zobrazení dokumentu OpenAPI ve formátu JSON.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Spusťte aplikaci a přejděte k https://localhost:<port>/openapi/v1.json zobrazení vygenerovaného dokumentu OpenAPI.

Možnosti přizpůsobení generování dokumentů OpenAPI

Následující části ukazují, jak přizpůsobit generování dokumentů OpenAPI.

Přizpůsobení názvu dokumentu OpenAPI

Každý dokument OpenAPI v aplikaci má jedinečný název. Výchozí název dokumentu, který je registrován, je v1.

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

Název dokumentu lze upravit předáním názvu jako parametru AddOpenApi volání.

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

Název dokumentu se zobrazí na několika místech v implementaci OpenAPI.

Při načítání vygenerovaného dokumentu OpenAPI je název dokumentu zadaný jako documentName argument parametru v požadavku. Následující žádosti tyto dokumenty a dokumenty vyřeší v1internal .

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

Přizpůsobení verze OpenAPI vygenerovaného dokumentu

Ve výchozím nastavení vytvoří generování dokumentů OpenAPI dokument, který vyhovuje specifikaci OpenAPI verze 3.0. Následující kód ukazuje, jak upravit výchozí verzi dokumentu OpenAPI:

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

Přizpůsobení trasy koncového bodu OpenAPI

Ve výchozím nastavení koncový bod OpenAPI zaregistrovaný prostřednictvím volání pro MapOpenApi zveřejnění dokumentu na koncovém /openapi/{documentName}.json bodu. Následující kód ukazuje, jak přizpůsobit trasu, ve které je dokument OpenAPI zaregistrovaný:

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

Je možné, ale nedoporučuje se odebrat documentName parametr trasy z trasy koncového bodu. documentName Když se parametr trasy odebere ze trasy koncového bodu, architektura se pokusí přeložit název dokumentu z parametru dotazu. Nezadávaní documentName trasy nebo dotazu může vést k neočekávanému chování.

Přizpůsobení koncového bodu OpenAPI

Vzhledem k tomu, že dokument OpenAPI se obsluhuje prostřednictvím koncového bodu obslužné rutiny trasy, je pro koncový bod OpenAPI k dispozici veškeré přizpůsobení, které je dostupné standardním minimálním koncovým bodům.

Omezení přístupu k dokumentům OpenAPI autorizovaným uživatelům

Koncový bod OpenAPI ve výchozím nastavení nepovoluje žádné kontroly autorizace. U dokumentu OpenAPI se ale dají použít kontroly autorizace. V následujícím kódu je přístup k dokumentu OpenAPI omezen na ty, které mají tester roli:

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

Dokument OpenAPI vygenerovaný v mezipaměti

Dokument OpenAPI se znovu vygeneruje při každém odeslání požadavku na koncový bod OpenAPI. Regenerace umožňuje transformátorům začlenit do provozu dynamický stav aplikace. Například opětovné vygenerování požadavku s podrobnostmi o kontextu HTTP. Pokud je to možné, dokument OpenAPI je možné uložit do mezipaměti, aby se zabránilo spuštění kanálu generování dokumentů na každém požadavku HTTP.

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

Generování dokumentů OpenAPI v době sestavení

V typických webových aplikacích se dokumenty OpenAPI generují za běhu a obsluhují se prostřednictvím požadavku HTTP aplikačního serveru.

V některých scénářích je užitečné vygenerovat dokument OpenAPI během kroku sestavení aplikace. Mezi tyto scénáře patří:

• Generování dokumentace OpenAPI, která je potvrzena do správy zdrojového kódu.
• Generování dokumentace OpenAPI, která se používá pro testování integrace založené na specifikacích.
• Generování dokumentace OpenAPI obsluhované staticky z webového serveru

Pokud chcete přidat podporu pro generování dokumentů OpenAPI v době sestavení, nainstalujte Microsoft.Extensions.ApiDescription.Server balíček:

Visual Studio

V konzole Správce balíčků spusťte následující příkaz:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

V adresáři, který obsahuje soubor projektu, spusťte následující příkaz:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Při instalaci tento balíček automaticky vygeneruje dokumenty rozhraní Open API přidružené k aplikaci během sestavování a naplní je do výstupního adresáře aplikace.

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

Přizpůsobení generování dokumentů v době sestavení

Úprava výstupního adresáře vygenerovaného souboru Open API

Ve výchozím nastavení se vygenerovaný dokument OpenAPI vygeneruje do výstupního adresáře aplikace. Chcete-li upravit umístění generovaného souboru, nastavte cílovou cestu ve OpenApiDocumentsDirectory vlastnosti.

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

Hodnota OpenApiDocumentsDirectory je vyřešena vzhledem k souboru projektu. ./ Použití výše uvedené hodnoty vygeneruje dokument OpenAPI ve stejném adresáři jako soubor projektu.

Úprava názvu výstupního souboru

Ve výchozím nastavení bude vygenerovaný dokument OpenAPI mít stejný název jako soubor projektu aplikace. Chcete-li změnit název vygenerovaného souboru, nastavte --file-name argument ve OpenApiGenerateDocumentsOptions vlastnosti.

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

Výběr dokumentu OpenAPI pro vygenerování

Některé aplikace můžou být nakonfigurované tak, aby vygenerovaly více dokumentů OpenAPI, pro různé verze rozhraní API nebo aby rozlišovaly mezi veřejnými a interními rozhraními API. Ve výchozím nastavení generátor dokumentů vygeneruje soubory pro všechny dokumenty nakonfigurované v aplikaci. Chcete-li vygenerovat pouze pro jeden název dokumentu, nastavte --document-name argument ve OpenApiGenerateDocumentsOptions vlastnosti.

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

Přizpůsobení chování za běhu během generování dokumentu v době sestavení

Funkce generování dokumentů OpenAPI během sestavení provedením spuštění vstupního bodu aplikací pomocí implementace napodobeného serveru. K vytvoření přesných dokumentů OpenAPI se vyžaduje napodobení serveru, protože všechny informace v dokumentu OpenAPI nelze staticky analyzovat. Vzhledem k tomu, že se vyvolá vstupní bod aplikace, spustí se také jakákoli logika při startu aplikace. To zahrnuje kód, který vloží služby do kontejneru DI nebo čte z konfigurace. V některých scénářích je nutné omezit cesty kódu, které se spustí při vyvolání vstupního bodu aplikace z generování dokumentu v době sestavení. Mezi tyto scénáře patří:

• Nečte se z určitých konfiguračních řetězců.
• Nezaregistrovává se databázové služby.

Aby bylo možné omezit vyvolávání těchto cest kódu infrastrukturou pro generování během doby sestavení, mohou být podmíněny kontrolou vstupního sestavení.

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 Přidává běžné .NET Aspire služby, jako je zjišťování služeb, odolnost, kontroly stavu a OpenTelemetry.

Oříznutí a nativní AOT

OpenAPI v ASP.NET Core podporuje optimalizaci a nativní AOT. Následující postup vytvoření a publikování aplikace OpenAPI s ořezáváním a nativním AOT:

Vytvořte nový projekt webového rozhraní API ASP.NET Core (nativní AOT).

dotnet new webapiaot

Přidejte balíček Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

Aktualizujte Program.cs, aby bylo možné generovat dokumenty OpenAPI.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Publikujte aplikaci.

dotnet publish