Aracılığıyla paylaş

ASP.NET Core API uygulamalarında OpenAPI desteği

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

ASP.NET Core, denetleyici tabanlı ve minimum API uygulamalarında OpenAPI belgelerinin oluşturulmasını destekler. OpenAPI belirtimi, HTTP API'lerini belgeleme için programlama dilinden bağımsız bir standarttır. Bu standart, ASP.NET Core uygulamalarında yerleşik API'ler ve açık kaynak kitaplıkların birleşimi aracılığıyla desteklenir. Bir uygulamada OpenAPI tümleştirmenin üç temel yönü vardır:

  • Uygulamadaki uç noktalar hakkında bilgi oluşturma.
  • Bilgileri OpenAPI şemasıyla eşleşen bir biçimde toplama.
  • Oluşturulan OpenAPI belgesini görsel kullanıcı arabirimi veya serileştirilmiş bir dosya aracılığıyla ortaya çıkarma.

ASP.NET Core uygulamaları, paket aracılığıyla Microsoft.AspNetCore.OpenApi bir uygulamadaki uç noktalar hakkında bilgi oluşturmak için yerleşik destek sağlar.

Aşağıdaki kod, ASP.NET Core minimal web API'si şablonu tarafından oluşturulur ve OpenAPI kullanır:

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

Yukarıdaki vurgulanan kodda:

  • AddOpenApi OpenAPI belge oluşturma için gereken hizmetleri uygulamanın DI kapsayıcısına kaydeder.
  • MapOpenApi , JSON olarak seri hale getirilmiş OpenAPI belgesini görüntülemek için uygulamaya bir uç nokta ekler. OpenAPI uç noktası, hassas bilgilerin açığa çıkma riskini en aza indirmek ve üretimdeki güvenlik açıklarını azaltmak için geliştirme ortamıyla sınırlıdır.

Microsoft.AspNetCore.OpenApi NuGet paketi

Paket Microsoft.AspNetCore.OpenApi aşağıdaki özellikleri sağlar:

  • Çalışma zamanında OpenAPI belgeleri oluşturma ve uygulamadaki bir uç nokta üzerinden bunlara erişme desteği.
  • Oluşturulan belgenin değiştirilmesine izin veren "transformatör" API'leri desteği.

Paketi kullanmak Microsoft.AspNetCore.OpenApi için bir proje dosyasına PackageReference olarak ekleyin:

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

Paket hakkında Microsoft.AspNetCore.OpenApi daha fazla bilgi edinmek için bkz . OpenAPI belgeleri oluşturma.

Microsoft.Extensions.ApiDescription.Server NuGet paketi

Paket, Microsoft.Extensions.ApiDescription.Server derleme zamanında OpenAPI belgeleri oluşturmak ve bunları serileştirmek için destek sağlar.

kullanmak Microsoft.Extensions.ApiDescription.Serveriçin bunu bir proje dosyasına PackageReference olarak ekleyin. Derleme zamanında belge oluşturma özelliği ayarlanarak OpenApiGenerateDocuments etkinleştirilir. Varsayılan olarak, oluşturulan OpenAPI belgesi dizine obj kaydedilir, ancak özelliğini ayarlayarak çıkış dizinini OpenApiDocumentsDirectory özelleştirebilirsiniz.

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

GitHub'da ASP.NET Core OpenAPI kaynak kodu

Ek Kaynaklar

OpenAPI belirtimi, HTTP API'lerini belgeleme için programlama dilinden bağımsız bir standarttır. Bu standart, yerleşik API'ler ve açık kaynak kitaplıkların birleşimi aracılığıyla minimum API'lerde desteklenir. Bir uygulamada OpenAPI tümleştirmenin üç temel yönü vardır:

  • Uygulamadaki uç noktalar hakkında bilgi oluşturma.
  • Bilgileri OpenAPI şemasıyla eşleşen bir biçimde toplama.
  • Oluşturulan OpenAPI şemasını görsel kullanıcı arabirimi veya serileştirilmiş bir dosya aracılığıyla ortaya çıkarma.

En düşük API'ler, paket aracılığıyla Microsoft.AspNetCore.OpenApi bir uygulamadaki uç noktalar hakkında bilgi oluşturmak için yerleşik destek sağlar. Oluşturulan OpenAPI tanımını görsel kullanıcı arabirimi aracılığıyla kullanıma sunma, üçüncü taraf bir paket gerektirir.

Denetleyici tabanlı API'lerde OpenAPI desteği hakkında bilgi için bu makalenin .NET 9 sürümüne bakın.