Obsługa interfejsu OpenAPI w aplikacjach interfejsu API platformy ASP.NET Core

ASP.NET Core obsługuje generowanie dokumentów OpenAPI w aplikacjach opartych na kontrolerach i minimalnych interfejsach API. Specyfikacja interfejsu OpenAPI to niezależny od języka programowania standard do dokumentowania interfejsów API PROTOKOŁU HTTP. Ten standard jest obsługiwany w aplikacjach ASP.NET Core za pomocą kombinacji wbudowanych interfejsów API i bibliotek open source. W aplikacji istnieją trzy kluczowe aspekty integracji interfejsu OpenAPI:

• Generowanie informacji o punktach końcowych w aplikacji.
• Zbieranie informacji w formacie zgodnym ze schematem OpenAPI.
• Uwidacznianie wygenerowanego dokumentu OpenAPI za pomocą wizualnego interfejsu użytkownika lub serializowanego pliku.

aplikacje ASP.NET Core zapewniają wbudowaną obsługę generowania informacji o punktach końcowych w aplikacji za pośrednictwem Microsoft.AspNetCore.OpenApi pakietu.

Poniższy kod jest generowany przez szablon interfejsu API internetowego ASP.NET Core i używa interfejsu OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

W poprzednim wyróżnionym kodzie:

• AddOpenApi rejestruje usługi wymagane do generowania dokumentów OpenAPI w kontenerze DI aplikacji.
• MapOpenApi dodaje punkt końcowy do aplikacji do wyświetlania dokumentu OpenAPI serializowanego w formacie JSON. Punkt końcowy interfejsu OpenAPI jest ograniczony do środowiska programistycznego, aby zminimalizować ryzyko ujawnienia poufnych informacji i zmniejszyć luki w zabezpieczeniach w środowisku produkcyjnym.

Microsoft.AspNetCore.OpenApi Pakiet NuGet

Pakiet Microsoft.AspNetCore.OpenApi 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.

Aby użyć Microsoft.AspNetCore.OpenApi pakietu, dodaj go jako packageReference do pliku projektu:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Aby dowiedzieć się więcej o pakiecie Microsoft.AspNetCore.OpenApi , zobacz Generowanie dokumentów OpenAPI.

Microsoft.Extensions.ApiDescription.Server Pakiet NuGet

Pakiet Microsoft.Extensions.ApiDescription.Server zapewnia obsługę generowania dokumentów OpenAPI w czasie kompilacji i ich serializacji.

Aby użyć Microsoft.Extensions.ApiDescription.Serverpolecenia , dodaj go jako element PackageReference do pliku projektu. Generowanie dokumentów w czasie kompilacji jest włączone przez ustawienie OpenApiGenerateDocuments właściwości . Domyślnie wygenerowany dokument OpenAPI jest zapisywany w obj katalogu, ale można dostosować katalog wyjściowy, ustawiając OpenApiDocumentsDirectory właściwość .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

kod źródłowy interfejsu OpenAPI platformy ASP.NET Core w witrynie GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Dodatkowe zasoby

• Uwierzytelnianie i autoryzacja w minimalnych interfejsach API