Podpora OpenAPI v aplikacích rozhraní API pro ASP.NET Core

ASP.NET Core podporuje generování dokumentů OpenAPI v aplikacích založených na kontroleru a minimálních rozhraníCH API. Specifikace OpenAPI je programovací standard nezávislý na jazyce pro dokumentaci rozhraní HTTP API. Tento standard se podporuje v aplikacích ASP.NET Core prostřednictvím kombinace integrovaných rozhraní API a opensourcových knihoven. Integrace OpenAPI v aplikaci má tři klíčové aspekty:

• Generování informací okoncovýchch
• Shromažďování informací do formátu, který odpovídá schématu OpenAPI.
• Vystavení vygenerovaného dokumentu OpenAPI prostřednictvím vizuálního uživatelského rozhraní nebo serializovaného souboru

aplikace ASP.NET Core poskytují integrovanou podporu generování informací o koncových bodech v aplikaci prostřednictvím Microsoft.AspNetCore.OpenApi balíčku.

Následující kód vygeneruje ASP.NET minimální šablona webového rozhraní API a používá 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);
}

V předchozím zvýrazněném kódu:

• AddOpenApi registruje služby potřebné pro generování dokumentů OpenAPI do kontejneru DI aplikace.
• MapOpenApi přidá do aplikace koncový bod pro zobrazení dokumentu OpenAPI serializovaného do formátu JSON. Koncový bod OpenAPI je omezený na vývojové prostředí, aby se minimalizovalo riziko vystavení citlivých informací a snížení ohrožení zabezpečení v produkčním prostředí.

Microsoft.AspNetCore.OpenApi Balíček NuGet

Balíček Microsoft.AspNetCore.OpenApi 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.

Pokud chcete balíček použít Microsoft.AspNetCore.OpenApi , přidejte ho jako PackageReference do souboru 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>

Další informace o Microsoft.AspNetCore.OpenApi balíčku najdete v tématu Generování dokumentů OpenAPI.

Microsoft.Extensions.ApiDescription.Server Balíček NuGet

Balíček Microsoft.Extensions.ApiDescription.Server poskytuje podporu pro generování dokumentů OpenAPI v době sestavení a jejich serializaci.

Pokud ho chcete použít Microsoft.Extensions.ApiDescription.Server, přidejte ho jako PackageReference do souboru projektu. Generování dokumentů v době sestavení je povoleno nastavením OpenApiGenerateDocuments vlastnosti. Ve výchozím nastavení se vygenerovaný dokument OpenAPI uloží do obj adresáře, ale výstupní adresář můžete přizpůsobit nastavením OpenApiDocumentsDirectory vlastnosti.

<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>

ASP.NET základní zdrojový kód OpenAPI na GitHubu

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Další materiály

• Ověřování a autorizace v minimálních rozhraních API