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 przekształcania, które umożliwiają modyfikowanie wygenerowanego dokumentu.
• Obsługa generowania wielu dokumentów OpenAPI z jednej aplikacji.
• Korzysta z obsługi schematu JSON udostępnianego przez System.Text.Jsonusługę .
• Jest zgodny z natywną usługą AoT.

Instalacja pakietu

Microsoft.AspNetCore.OpenApi Zainstaluj pakiet:

Program Visual Studio

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

Install-Package Microsoft.AspNetCore.OpenApi

Interfejs wiersza polecenia platformy .NET

Uruchom następujące polecenie:

dotnet add package Microsoft.AspNetCore.OpenApi

Konfigurowanie generowania dokumentów interfejsu OpenAPI

Następujący kod powoduje:

• Dodaje usługi OpenAPI.
• Włącza punkt końcowy do wyświetlania dokumentu OpenAPI w formacie JSON.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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 rozpoznają v1 dokumenty 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 dokumentów OpenAPI tworzy dokument zgodny ze specyfikacją interfejsu 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;
});

Dostosowywanie trasy punktu końcowego interfejsu OpenAPI

Domyślnie punkt końcowy interfejsu OpenAPI zarejestrowany za pośrednictwem wywołania MapOpenApi uwidacznia dokument w /openapi/{documentName}.json punkcie końcowym. 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, aby usunąć documentName parametr trasy z trasy punktu końcowego. Po usunięciu parametru documentName trasy z trasy punktu końcowego struktura próbuje rozpoznać nazwę dokumentu z parametru zapytania. Brak podania documentName w trasie lub kwerendzie może spowodować nieoczekiwane zachowanie.

Dostosowywanie punktu końcowego interfejsu OpenAPI

Ponieważ dokument OpenAPI jest obsługiwany za pośrednictwem punktu końcowego procedury obsługi tras, wszelkie dostosowania dostępne dla standardowych minimalnych punktów końcowych są dostępne 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. Regeneruj umożliwia przekształcanie w ich działanie dynamicznego stanu aplikacji. 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 dokumentów w każdym żądaniu 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();

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 na serwerze aplikacji.

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

• Generowanie dokumentacji interfejsu OpenAPI zatwierdzonej do kontroli źródła.
• 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:

Program Visual Studio

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

Install-Package Microsoft.Extensions.ApiDescription.Server

Interfejs wiersza polecenia platformy .NET

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

dotnet add package Microsoft.Extensions.ApiDescription.Server

Po zainstalowaniu ten pakiet automatycznie wygeneruje dokumenty open API skojarzone z aplikacją podczas kompilacji i wypełni je w katalogu wyjściowym aplikacji.

$ dotnet build
$ cat bin/Debug/net9.0/{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 rozpoznawana 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 argument we OpenApiGenerateDocumentsOptions właściwości .

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

Wybieranie dokumentu OpenAPI do wygenerowania

Niektóre aplikacje mogą być skonfigurowane do emitowania wielu dokumentów OpenAPI dla różnych wersji interfejsu API lub rozróżniania między publicznymi i wewnętrznymi interfejsami API. Domyślnie generator dokumentów w czasie kompilacji będzie emitować pliki dla wszystkich dokumentów skonfigurowanych w aplikacji. Aby emitować tylko dla pojedynczej nazwy dokumentu, ustaw --document-name argument we OpenApiGenerateDocumentsOptions właściwości .

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

Dostosowywanie zachowania czasu wykonywania podczas generowania dokumentu w czasie kompilacji

Pod maską funkcje generowania dokumentów OpenAPI w czasie kompilacji, uruchamiając punkt wejścia aplikacji z implementacją serwera inert. Jest to wymóg tworzenia dokładnych dokumentów OpenAPI, ponieważ nie można statycznie analizować wszystkich informacji w dokumencie OpenAPI. Ponieważ punkt wejścia aplikacji jest wywoływany, zostanie wywołana 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 po wywołaniu punktu wejścia aplikacji z generowania dokumentu w czasie kompilacji. Scenariusze obejmują:

• Nie można odczytać 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 potok generowania czasu kompilacji, można je określić za sprawdzeniem zestawu wejściowego w następujący sposób:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

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