Generowanie dokumentów OpenAPI

Pakiet Microsoft.AspNetCore.OpenApi zapewnia wbudowaną obsługę generowania dokumentów OpenAPI w programie ASP.NET Core. Pakiet udostępnia następujące funkcje:

• Obsługa generowania dokumentów OpenAPI w czasie wykonywania i uzyskiwania do nich dostępu za pośrednictwem punktu końcowego w aplikacji.
• Obsługa interfejsów API typu "transformer", które pozwalają na modyfikację wygenerowanego dokumentu.
• Obsługa generowania wielu dokumentów OpenAPI z jednej aplikacji.
• Korzysta z obsługi schematu JSON udostępnianego przez System.Text.Json.
• Jest zgodny z natywną funkcją AoT.

Instalacja pakietu

Microsoft.AspNetCore.OpenApi Zainstaluj pakiet:

Visual Studio

Uruchom następujące polecenie w konsoli Menedżer pakietów:

Install-Package Microsoft.AspNetCore.OpenApi

Interfejs wiersza poleceń .NET

Uruchom następujące polecenie:

dotnet add package Microsoft.AspNetCore.OpenApi

Konfigurowanie generowania dokumentów interfejsu OpenAPI

Następujący kod:

• Dodaje usługi OpenAPI przy użyciu metody rozszerzenia AddOpenApi w kolekcji usług konstruktora aplikacji.
• Mapuje punkt końcowy do wyświetlania dokumentu OpenAPI w formacie JSON za pomocą metody rozszerzenia MapOpenApi w aplikacji.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Uruchom aplikację i przejdź do https://localhost:<port>/openapi/v1.json strony , aby wyświetlić wygenerowany dokument OpenAPI.

Opcje dostosowywania generowania dokumentów interfejsu OpenAPI

W poniższych sekcjach pokazano, jak dostosować generowanie dokumentów interfejsu OpenAPI.

Dostosowywanie nazwy dokumentu OpenAPI

Każdy dokument OpenAPI w aplikacji ma unikatową nazwę. Domyślna nazwa zarejestrowanego dokumentu to v1.

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

Nazwę dokumentu można zmodyfikować, przekazując nazwę jako parametr do wywołania AddOpenApi .

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

Nazwa dokumentu jest wyświetlana w kilku miejscach w implementacji interfejsu OpenAPI.

Podczas pobierania wygenerowanego dokumentu OpenAPI nazwa dokumentu jest podawana jako documentName argument parametru w żądaniu. Następujące żądania rozstrzygają dokumenty v1 i internal.

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

Dostosowywanie wersji interfejsu OpenAPI wygenerowanego dokumentu

Domyślnie, generowanie dokumentu OpenAPI tworzy dokument zgodny ze specyfikacją OpenAPI w wersji 3.0. Poniższy kod pokazuje, jak zmodyfikować domyślną wersję dokumentu OpenAPI:

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

Dostosuj ścieżkę punktu końcowego interfejsu OpenAPI

Domyślnie punkt końcowy interfejsu OpenAPI zarejestrowany za pośrednictwem wywołania MapOpenApi uwidacznia dokument w punkcie końcowym /openapi/{documentName}.json. Poniższy kod pokazuje, jak dostosować trasę, w której zarejestrowano dokument OpenAPI:

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

Możliwe, ale nie jest zalecane usunięcie parametru trasy documentName z trasy końcowej. Po usunięciu parametru documentName z ścieżki punktu końcowego, platforma próbuje rozpoznać nazwę dokumentu z parametru zapytania. Brak podania documentName w ścieżce lub kwerendzie może spowodować nieprzewidziane zachowanie.

Dostosowywanie punktu końcowego interfejsu OpenAPI

Ponieważ dokument OpenAPI jest obsługiwany za pośrednictwem punktu końcowego obsługującego trasę, wszystkie dostosowania dostępne dla standardowych minimalnych punktów końcowych są dostępne także dla punktu końcowego interfejsu OpenAPI.

Ograniczanie dostępu do dokumentów OpenAPI autoryzowanym użytkownikom

Punkt końcowy interfejsu OpenAPI domyślnie nie włącza żadnych testów autoryzacji. Jednak kontrole autoryzacji można zastosować do dokumentu OpenAPI. W poniższym kodzie dostęp do dokumentu OpenAPI jest ograniczony do osób z 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();

Dokument OpenAPI wygenerowany w pamięci podręcznej

Dokument OpenAPI jest ponownie wygenerowany przy każdym wysłaniu żądania do punktu końcowego interfejsu OpenAPI. Regeneracja umożliwia transformatorom inkorporowanie dynamicznego stanu aplikacji do ich działania. Na przykład ponowne generowanie żądania ze szczegółami kontekstu HTTP. Jeśli ma to zastosowanie, dokument OpenAPI można buforować, aby uniknąć wykonywania potoku generowania dokumentu dla każdego żądania 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();

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

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

app.Run();

Generowanie wielu dokumentów OpenAPI

W niektórych scenariuszach pomocne jest wygenerowanie wielu dokumentów OpenAPI o różnej zawartości z jednej aplikacji API ASP.NET Core. Scenariusze obejmują:

• Generowanie dokumentacji OpenAPI zarówno dla publicznych, jak i wewnętrznych API.
• Generowanie dokumentacji interfejsu OpenAPI dla różnych wersji interfejsu API.
• Generowanie dokumentacji interfejsu OpenAPI dla różnych części aplikacji, takich jak interfejs API frontonu i zaplecza.

Aby wygenerować wiele dokumentów OpenAPI, wywołaj metodę rozszerzenia AddOpenApi raz dla każdego dokumentu, określając inną nazwę dokumentu w pierwszym parametrze za każdym razem.

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

Każde wywołanie AddOpenApi może określać własny zestaw opcji, dzięki czemu można użyć tych samych lub różnych dostosowań dla każdego dokumentu OpenAPI.

Struktura używa metody delegata ShouldIncludeOpenApiOptions, aby określić, które punkty końcowe mają być uwzględnione w każdym dokumencie.

Dla każdego dokumentu metoda delegata ShouldInclude jest wywoływana dla każdego punktu końcowego w aplikacji, przekazując obiekt ApiDescription dla punktu końcowego. Metoda zwraca wartość logiczną wskazującą, czy punkt końcowy powinien zostać uwzględniony w dokumencie. Obiekt ApiDescription:

• zawiera informacje o punkcie końcowym, takie jak metoda HTTP, trasa i typy odpowiedzi
• Metadane dołączone do punktu końcowego za pomocą atrybutów lub metod rozszerzenia.

Domyślna implementacja tego delegata używa pola GroupName obiektu ApiDescription. Delegat jest definiowany w punkcie końcowym za pomocą metody rozszerzenia WithGroupName lub atrybutu EndpointGroupNameAttribute. WithGroupName lub atrybut EndpointGroupName określa, które punkty końcowe mają być uwzględnione w dokumencie. Każdy punkt końcowy, który nie został przypisany do nazwy grupy, jest uwzględniony we wszystkich dokumentach OpenAPI.

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

Możesz dostosować metodę delegata ShouldInclude, aby uwzględnić lub wykluczyć punkty końcowe na podstawie dowolnych kryteriów.

Generowanie dokumentów OpenAPI w czasie kompilacji

W typowych aplikacjach internetowych dokumenty OpenAPI są generowane w czasie wykonywania i obsługiwane za pośrednictwem żądania HTTP do serwera aplikacji.

W niektórych scenariuszach warto wygenerować dokument OpenAPI podczas kroku kompilacji aplikacji. Scenariusze obejmują:

• Generowanie dokumentacji interfejsu OpenAPI zatwierdzonej w systemie kontroli wersji.
• Generowanie dokumentacji interfejsu OpenAPI używanej do testowania integracji opartego na specyfikacji.
• Generowanie dokumentacji interfejsu OpenAPI obsługiwanej statycznie z serwera internetowego.

Aby dodać obsługę generowania dokumentów OpenAPI w czasie kompilacji, zainstaluj Microsoft.Extensions.ApiDescription.Server pakiet:

Visual Studio

Uruchom następujące polecenie w konsoli Menedżer pakietów:

Install-Package Microsoft.Extensions.ApiDescription.Server

Interfejs wiersza poleceń .NET

Uruchom następujące polecenie w katalogu zawierającym plik projektu:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Po zainstalowaniu tego pakietu:

• Automatycznie generuje dokumenty open API skojarzone z aplikacją podczas kompilacji.
• Umieszcza dokumenty Open API w katalogu wyjściowym aplikacji.

Jeśli zarejestrowano wiele dokumentów, i nazwa dokumentu nie jest v1, jest dołączona na końcu z nazwą dokumentu. Np. {ProjectName}_{DocumentName}.json.

Visual Studio Code

dotnet build
type obj\{ProjectName}.json

CLI .NET Core

dotnet build
cat obj/{ProjectName}.json

Dostosowywanie generowania dokumentu w czasie kompilacji

Modyfikowanie katalogu wyjściowego wygenerowanego pliku open API

Domyślnie wygenerowany dokument OpenAPI będzie emitowany do katalogu wyjściowego aplikacji. Aby zmodyfikować lokalizację emitowanego pliku, ustaw ścieżkę docelową OpenApiDocumentsDirectory we właściwości .

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

Wartość parametru OpenApiDocumentsDirectory jest ustalana względem pliku projektu. Użycie powyższej . wartości spowoduje emitowanie dokumentu OpenAPI w tym samym katalogu co plik projektu.

Modyfikowanie nazwy pliku wyjściowego

Domyślnie wygenerowany dokument OpenAPI będzie miał taką samą nazwę jak plik projektu aplikacji. Aby zmodyfikować nazwę emitowanego pliku, ustaw --file-name parametr w OpenApiGenerateDocumentsOptions właściwości.

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

Wybieranie dokumentu OpenAPI do wygenerowania

Niektóre aplikacje można skonfigurować do emitowania wielu dokumentów OpenAPI. Dla różnych wersji interfejsu API można wygenerować wiele dokumentów OpenAPI lub rozróżniać publiczne i wewnętrzne interfejsy API. Domyślnie generator dokumentów w czasie kompilacji emituje pliki dla wszystkich dokumentów skonfigurowanych w aplikacji. Aby wyprowadzać wynik tylko dla pojedynczej nazwy dokumentu, ustaw argument --document-name we właściwości OpenApiGenerateDocumentsOptions.

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

Dostosowywanie zachowania czasu wykonywania podczas generowania dokumentu w czasie kompilacji

Funkcje generowania dokumentów OpenAPI na etapie budowania przez uruchomienie punktu startowego aplikacji z implementacją symulowanego serwera. Do utworzenia dokładnych dokumentów OpenAPI wymagany jest pozorowany serwer, ponieważ nie można statycznie analizować wszystkich informacji w dokumencie OpenAPI. Ponieważ wywoływany jest punkt wejścia aplikacji, wywoływana jest dowolna logika podczas uruchamiania aplikacji. Obejmuje to kod, który wprowadza usługi do kontenera DI lub odczytuje z konfiguracji. W niektórych scenariuszach należy ograniczyć ścieżki kodu, które będą uruchamiane, kiedy punkt wejścia aplikacji jest wywoływany podczas generowania dokumentów w czasie kompilacji. Scenariusze obejmują:

• Brak odczytu z niektórych ciągów konfiguracji.
• Nie rejestruje usług związanych z bazą danych.

Aby ograniczyć wywoływanie tych ścieżek kodu przez mechanizm generowania w czasie kompilacji, można je warunkować sprawdzaniem zestawu początkowego:

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 dodaje typowe usługi .NET Aspire, takie jak odnajdywanie usług, odporność, kontrole kondycji i openTelemetry.

Przycinanie i natywne kompilowanie AOT

Interfejs OpenAPI w programie ASP.NET Core obsługuje przycinanie i natywną funkcję AOT. Poniższe kroki umożliwiają utworzenie i opublikowanie aplikacji OpenAPI z przycinaniem i natywną funkcją AOT:

Utwórz nowy projekt ASP.NET Core Web API (Native AOT).

dotnet new webapiaot

Dodaj pakiet Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi

Zaktualizuj Program.cs, aby umożliwić generowanie dokumentów OpenAPI.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Opublikuj aplikację.

dotnet publish