Aracılığıyla paylaş

OpenAPI belgeleri oluşturma

  • Makale

Paket, Microsoft.AspNetCore.OpenApi ASP.NET Core'da OpenAPI belge oluşturma için yerleşik destek sağlar. Paket aşağıdaki özellikleri sağlar:

  • Çalışma zamanında OpenAPI belgeleri oluşturma ve bunlara uygulamadaki bir uç nokta üzerinden erişme desteği.
  • Oluşturulan belgenin değiştirilmesine izin veren "transformatör" API'leri desteği.
  • Tek bir uygulamadan birden çok OpenAPI belgesi oluşturma desteği.
  • tarafından sağlanan JSON şema desteğinden yararlanır System.Text.Json.
  • Yerel AoT ile uyumludur.

Paket yükleme

Microsoft.AspNetCore.OpenApi Paketi yükleyin:

Paket Yöneticisi Konsolu'ndan aşağıdaki komutu çalıştırın:

Install-Package Microsoft.AspNetCore.OpenApi

OpenAPI belge oluşturmayı yapılandırma

Aşağıdaki kod:

  • Uygulama oluşturucusunun hizmet koleksiyonundaki AddOpenApi uzantısı yöntemini kullanarak OpenAPI hizmetlerini ekler.
  • OpenAPI belgesini JSON biçiminde görüntülemek için bir uç noktayı uygulamadaki MapOpenApi uzantısı yöntemiyle eşler.
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Uygulamayı başlatın ve oluşturulan OpenAPI belgesini görüntülemek için adresine gidin https://localhost:<port>/openapi/v1.json .

OpenAPI belge oluşturmayı özelleştirme seçenekleri

Aşağıdaki bölümlerde OpenAPI belge oluşturma işleminin nasıl özelleştirileceği gösterilmektedir.

OpenAPI belge adını özelleştirme

Bir uygulamadaki her OpenAPI belgesinin benzersiz bir adı vardır. Kaydedilen varsayılan belge adıdır v1.

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

AddOpenApi çağrısına belge adı parametre olarak geçirilerek değiştirilebilir.

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

Belge adı, OpenAPI uygulamasında çeşitli yerlerde görünür.

Oluşturulan OpenAPI belgesi getirilirken, belge adı istekte documentName parametresi olarak sağlanır. Aşağıdaki istekler v1 ve internal belgelerini çözer.

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

Oluşturulan belgenin OpenAPI sürümünü özelleştirme

Varsayılan olarak, OpenAPI belge oluşturma, OpenAPI belirtiminin v3.0 ile uyumlu bir belge oluşturur. Aşağıdaki kod, OpenAPI belgesinin varsayılan sürümünün nasıl değiştirileceği gösterilmektedir:

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

OpenAPI uç noktası yolunu özelleştirme

Varsayılan olarak, MapOpenApi ile kaydedilen OpenAPI uç noktası, belgeyi /openapi/{documentName}.json uç noktasında kullanıma sunar. Aşağıdaki kodda, OpenAPI belgesinin kaydedildiği yolun nasıl özelleştirileceği gösterilmektedir:

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

Yol parametresini uç nokta yolundan documentName kaldırmak mümkündür ancak önerilmez. documentName Yol parametresi uç nokta yolundan kaldırıldığında, çerçeve sorgu parametresinden belge adını çözümlemeye çalışır. Rota veya sorguda documentName sağlanmayan, beklenmeyen davranışa neden olabilir.

OpenAPI uç noktasını özelleştirme

OpenAPI belgesi bir yol işleyicisi uç noktası aracılığıyla sunulduğundan, standart en düşük uç noktalarda kullanılabilen tüm özelleştirmeler OpenAPI uç noktası tarafından kullanılabilir.

OpenAPI belge erişimini yetkili kullanıcılarla sınırlama

OpenAPI uç noktası varsayılan olarak hiçbir yetkilendirme denetimini etkinleştirmez. Ancak, yetkilendirme denetimleri OpenAPI belgesine uygulanabilir. Aşağıdaki kodda, OpenAPI belgesine erişim rolüne tester sahip olanlarla sınırlıdır:

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

Önbellekle oluşturulan OpenAPI belgesi

OpenAPI belgesi, OpenAPI uç noktasına her istek gönderildiğinde yeniden oluşturulur. Yeniden oluşturma, transformatörlerin dinamik uygulama durumunu çalışmalarına dahil etmelerini sağlar. Örneğin, isteği HTTP bağlamının ayrıntılarıyla yeniden oluşturma. Uygun olduğunda, her HTTP isteğinde belge oluşturma işlem hattının yürütülmesini önlemek için OpenAPI belgesi önbelleğe alınabilir.

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

Birden çok OpenAPI belgesi oluşturma

Bazı senaryolarda, tek bir ASP.NET Core API uygulamasından farklı içeriğe sahip birden çok OpenAPI belgesi oluşturmak yararlı olur. Bu senaryolar şunlardır:

  • Genel ve iç API'ler gibi farklı hedef kitleler için OpenAPI belgeleri oluşturma.
  • Bir API'nin farklı sürümleri için OpenAPI belgeleri oluşturma.
  • Uygulamanın ön uç ve arka uç API'si gibi farklı bölümleri için OpenAPI belgeleri oluşturma.

Birden çok OpenAPI belgesi oluşturmak için her belge için AddOpenApi uzantısı yöntemini bir kez çağırın ve her seferinde ilk parametrede farklı bir belge adı belirtin.

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

her AddOpenApi çağrısı kendi seçenek kümesini belirtebilir, böylece her OpenAPI belgesi için aynı veya farklı özelleştirmeleri kullanmayı seçebilirsiniz.

Çerçeve, her belgeye dahil edilecek uç noktaları belirlemek için ShouldInclude'in OpenApiOptions temsilci yöntemini kullanır.

Her belge için, uygulamadaki her uç nokta için ShouldInclude temsilci yöntemi çağrılır ve bu uç noktaya ApiDescription nesnesi geçirilir. yöntemi, uç noktanın belgeye eklenip eklenmeyeceğini belirten bir boole değeri döndürür. Nesne ApiDescription:

  • HTTP yöntemi, yol ve yanıt türleri gibi uç nokta hakkında bilgi içerir
  • Öznitelikler veya uzantı yöntemleri aracılığıyla uç noktaya eklenen meta veriler.

Bu temsilcinin varsayılan uygulaması, GroupNameApiDescription alanını kullanır. Temsilci, WithGroupName uzantısı yöntemi veya EndpointGroupNameAttribute özniteliği kullanılarak bir uç noktada ayarlanır. WithGroupName veya EndpointGroupName özniteliği, belgeye eklenecek uç noktaları belirler. Bir grup adı atanmamış tüm uç noktalar tüm OpenAPI belgelerine eklenir.

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

seçtiğiniz ölçütlere göre uç noktaları dahil etmek veya dışlamak için ShouldInclude temsilci yöntemini özelleştirebilirsiniz.

Derleme zamanında OpenAPI belgeleri oluşturun

Tipik web uygulamalarında OpenAPI belgeleri çalışma zamanında oluşturulur ve uygulama sunucusuna bir HTTP isteği aracılığıyla sunulur.

Bazı senaryolarda, uygulamanın derleme adımı sırasında OpenAPI belgesini oluşturmak yararlı olur. Bu senaryolar şunlardır:

  • Kaynak denetimine kaydedilmiş OpenAPI belgeleri oluşturma.
  • Belirtim tabanlı tümleştirme testi için kullanılan OpenAPI belgeleri oluşturma.
  • Web sunucusundan statik olarak sunulan OpenAPI belgeleri oluşturma.

Derleme zamanında OpenAPI belgeleri oluşturma desteği eklemek için paketini yükleyin Microsoft.Extensions.ApiDescription.Server :

Paket Yöneticisi Konsolu'ndan aşağıdaki komutu çalıştırın:

Install-Package Microsoft.Extensions.ApiDescription.Server

Yükleme tamamlandığında, bu paket:

  • Derleme sırasında uygulamayla ilişkili Open API belgelerini otomatik olarak oluşturur.
  • Uygulamanın çıkış dizinindeki Open API belgelerini doldurur.

Birden çok belge kaydedildiyse, ve belge adı değilv1, belge adından sonra eklenir. Örneğin, {ProjectName}_{DocumentName}.json.

dotnet build
type obj\{ProjectName}.json

Yapı zamanı belge oluşturmayı özelleştirme

Oluşturulan Open API dosyasının çıkış dizinini değiştirme

Varsayılan olarak, oluşturulan OpenAPI belgesi uygulamanın çıkış dizinine gönderilir. Yayılan dosyanın konumunu değiştirmek için özelliğinde OpenApiDocumentsDirectory hedef yolu ayarlayın.

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

Değeri OpenApiDocumentsDirectory proje dosyasına göre hesaplanır. Yukarıdaki değerin . kullanılması OpenAPI belgesini proje dosyasıyla aynı dizinde gösterir.

Çıktı dosyasının adını değiştirme

Varsayılan olarak, oluşturulan OpenAPI belgesi uygulamanın proje dosyasıyla aynı ada sahip olur. Yayılan dosyanın adını değiştirmek için --file-name özelliğinde OpenApiGenerateDocumentsOptions bağımsız değişkenini ayarlayın.

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

Oluşturulacak OpenAPI belgesini seçme

Bazı uygulamalar birden çok OpenAPI belgesi yayacak şekilde yapılandırılabilir. Bir API'nin farklı sürümleri için veya genel ve iç API'ler arasında ayrım yapmak için birden çok OpenAPI belgesi oluşturulabilir. Varsayılan olarak, derleme sürecinde belge oluşturucu, bir uygulamada yer alan ve yapılandırılmış tüm belgeler için dosyalar oluşturur. Yalnızca tek bir belge adı yaymak için --document-name özelliğinde OpenApiGenerateDocumentsOptions bağımsız değişkenini ayarlayın.

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

Yapı zamanı belge oluşturma sırasında çalışma zamanındaki davranışı özelleştirme

Derleme zamanı OpenAPI belge oluşturma işlevlerini, uygulama giriş noktasını bir sahte sunucu uygulamasıyla başlatarak gerçekleştirin. OpenAPI belgesindeki tüm bilgiler statik olarak çözümlenemediğinden, doğru OpenAPI belgeleri oluşturmak için sahte sunucu gereklidir. Uygulama giriş noktası çağrıldığından, uygulama başlatmadaki tüm mantık çağrılır. Bu, hizmetleri DI kapsayıcısına enjekte eden veya yapılandırmadan okuyan kodunu içerir. Bazı senaryolarda, uygulamanın giriş noktası derleme sırasında belge oluşturma işleminden çağrıldığında çalışacak kod yollarını kısıtlamak gerekir. Bu senaryolar şunlardır:

  • Bazı yapılandırma dizgilerinden okunmuyor.
  • Veritabanıyla ilgili hizmetler kaydedilmiyor.

Bu kod yollarının derleme zamanı oluşturma işlem hattı tarafından çağrılmasını kısıtlamak için, giriş derlemesi kontrol edilerek koşullandırılabilir.

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 hizmet bulma, dayanıklılık, sistem durumu denetimleri ve OpenTelemetry gibi yaygın .NET Aspire hizmetleri ekler.

Kırpma ve Yerel AOT

ASP.NET Core'da OpenAPI kırpmayı ve yerel AOT'yi destekler. Aşağıdaki adımlar, kırpma ve yerel AOT teknolojileri ile bir OpenAPI uygulaması oluşturur ve yayımlar:

Yeni bir ASP.NET Core Web API (Yerel AOT) projesi oluşturun.

dotnet new webapiaot

Microsoft.AspNetCore.OpenAPI paketini ekleyin.

dotnet add package Microsoft.AspNetCore.OpenApi

OpenAPI belgeleri oluşturmayı etkinleştirmek için Program.cs güncelleştirin.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Uygulamayı yayımlayın.

dotnet publish

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.

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.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

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")
.WithOpenApi();

app.Run();

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

Yukarıdaki vurgulanan kodda:

  • Microsoft.AspNetCore.OpenApi sonraki bölümde açıklanmıştır.
  • AddEndpointsApiExplorer : Varsayılan ek açıklamalarla uç noktaları bulmak ve açıklamak için uygulamayı API Gezgini'ni kullanacak şekilde yapılandırılır. WithOpenApi tarafından üretilen varsayılan ek açıklamaları API Gezgini paketi Microsoft.AspNetCore.OpenApi ile eşleştirip geçersiz kılar.
  • UseSwagger Swagger ara yazılımını ekler.
  • 'UseSwaggerUI', Swagger UI aracının eklenmiş bir sürümünü etkinleştirir.
  • WithName IEndpointNameMetadata: Uç nokta üzerindeki bağlantı oluşturma için kullanılır ve verilen uç noktanın OpenAPI belirtiminde işlem kimliği olarak değerlendirilir.
  • WithOpenApi bu makalenin devamında açıklanmıştır.

Microsoft.AspNetCore.OpenApi NuGet paketi

ASP.NET Core, uç noktalar için OpenAPI belirtimleriyle etkileşime geçmek için paket sağlar Microsoft.AspNetCore.OpenApi . Paket, pakette tanımlanan OpenAPI modelleri ile En Düşük API'lerde Microsoft.AspNetCore.OpenApi tanımlanan uç noktalar arasında bir bağlantı işlevi görür. Paket, uç noktayı açıklamak için kullanılan bir OpenAPI ek açıklama türü oluşturmak için uç noktanın parametrelerini, yanıtlarını ve meta verilerini inceleyen bir API sağlar.

Microsoft.AspNetCore.OpenApi bir proje dosyasına PackageReference olarak eklenir:

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

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

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

ile Swashbuckle.AspNetCoreMicrosoft.AspNetCore.OpenApi kullanıldığındaSwashbuckle.AspNetCore, 6.4.0 veya üzeri kullanılmalıdır. Microsoft.OpenApi Çağırmalarda WithOpenApi kopya oluşturuculardan yararlanmak için 1.4.3 veya üzeri kullanılmalıdır.

Uç noktalara OpenAPI açıklamaları eklemek için WithOpenApi kullanın

Uç noktada WithOpenApi çağrıldığında, uç noktanın meta verilerine ekleme yapılır. Bu meta veriler şu şekilde olabilir:

  • Swashbuckle.AspNetCore gibi üçüncü taraf paketlerde tüketilir.
  • Swagger kullanıcı arabiriminde veya API'yi tanımlamak için oluşturulan YAML veya JSON'da görüntülenir.
app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();

OpenAPI ek açıklamasını WithOpenApi değiştir

yöntemi, WithOpenApi OpenAPI ek açıklamasını değiştirmek için kullanılabilecek bir işlevi kabul eder. Örneğin, aşağıdaki kodda uç noktanın ilk parametresine bir açıklama eklenir:

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

OpenAPI'ye işlem kimlikleri ekleme

İşlem kimlikleri, OpenAPI'de belirli bir uç noktayı benzersiz olarak tanımlamak için kullanılır. WithName Uzantı yöntemi, bir yöntem için kullanılan işlem kimliğini ayarlamak için kullanılabilir.

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Alternatif olarak, OperationId özelliği doğrudan OpenAPI ek açıklamasında ayarlanabilir.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

OpenAPI açıklamasına etiket ekleme

OpenAPI, işlemleri kategorilere ayırmak için etiket nesnelerinin kullanılmasını destekler. Bu etiketler genellikle Swagger kullanıcı arabirimindeki işlemleri gruplandırmak için kullanılır. Bu etiketler, istenen etiketlerle birlikte uç nokta üzerinde WithTags uzantı yöntemi çağrılarak bir işleme eklenebilir.

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

Alternatif olarak, OpenApiTags uzantı yöntemi aracılığıyla OpenAPI ek açıklamasında WithOpenApi listesi ayarlanabilir.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

Uç nokta özeti veya açıklaması ekleme

Uç nokta özeti ve açıklaması, WithOpenApi uzantı yöntemi çağrılarak eklenebilir. Aşağıdaki kodda özetler doğrudan OpenAPI annotasyonunda ayarlanır.

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

OpenAPI açıklamasını dışla

Aşağıdaki örnekte, /skipme uç nokta openAPI açıklaması oluşturmanın dışında tutulur:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

API'yi eski olarak işaretleme

Uç noktayı kullanım dışı olarak işaretlemek için, OpenAPI açıklamasında Deprecated özelliğini ayarlayın.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

Yanıt türlerini açıklama

OpenAPI, API'den döndürülen yanıtların açıklamasını sağlamayı destekler. Minimum API'ler, bir uç noktanın yanıt türünü ayarlamak için üç stratejiyi destekler:

Produces uzantı yöntemi, bir uç noktaya Produces meta verisi eklemek için kullanılabilir. Hiçbir parametre sağlanmamışsa, uzantı yöntemi hedeflenen tür için meta verileri bir 200 durum kodu ve application/json içerik türü altında doldurur.

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

Uç noktanın yol işleyicisinin uygulanmasında kullanılması TypedResults , uç nokta için yanıt türü meta verilerini otomatik olarak içerir. Örneğin, aşağıdaki kod, 200 içerik türüne ve application/json durum koduna sahip bir yanıt ile uç noktayı otomatik olarak açıklama ekler.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

Yanıtları ayarla ProblemDetails

ProblemDetails yanıtı döndürebilecek uç noktalar için yanıt türünü ayarlarken, uzantı yöntemi ProducesProblemveya ProducesValidationProblem uç noktanın TypedResults.Problem meta verilerine uygun ek açıklamayı eklemek için kullanılabilir. ProducesProblem ve ProducesValidationProblem uzantı yöntemlerinin .NET 8 ve önceki sürümlerde yol grupları ile kullanılamayacağını unutmayın.

Yukarıdaki stratejilerden biri tarafından sağlanan açık ek açıklamalar olmadığında, çerçeve yanıtın imzasını inceleyerek varsayılan yanıt türünü belirlemeye çalışır. Bu varsayılan yanıt, OpenAPI tanımındaki 200 durum kodu altında doldurulur.

Birden çok yanıt türü

Bir uç nokta farklı senaryolarda farklı yanıt türleri döndürebiliyorsa meta verileri aşağıdaki yollarla sağlayabilirsiniz:

  • Produces Aşağıdaki örnekte gösterildiği gibi uzantı yöntemini birden çok kez çağırın:

    app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

  • Aşağıdaki örnekte gösterildiği gibi, Results<TResult1,TResult2,TResultN>'i imzada ve TypedResults'i işleyicinin gövdesinde kullanın:

    app.MapGet("/book/{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
{
    return bookList.FirstOrDefault((i) => i.Id == id) is Book book
     ? TypedResults.Ok(book)
     : TypedResults.NotFound();
});

    Birleşim Results<TResult1,TResult2,TResultN>türleri , bir yol işleyicisinin birden çok IResult uygulayan somut tür döndürdüğünü ve bu türlerden herhangi birinin IEndpointMetadataProvider uygulaması halinde uç noktanın meta verilerine katkıda bulunacağını bildirir.

    Birleşim türleri örtük dönüşüm operatörlerini uygular. Bu işleçler, derleyicinin genel bağımsız değişkenlerde belirtilen türleri birleşim türünün bir örneğine otomatik olarak dönüştürmesini sağlar. Bu özellik, bir yol işleyicisinin yalnızca bildirdiği sonuçları döndürdüğüne ilişkin derleme zamanı denetimi sağlama avantajına sahiptir. Results<TResult1,TResult2,TResultN>'ye genel bağımsız değişkenlerden biri olarak bildirilmeyen bir tür döndürmeye çalışmak derleme hatasına neden olur.

İstek gövdesini ve parametrelerini açıklama

Uç nokta tarafından döndürülen türleri açıklamaya ek olarak, OpenAPI bir API tarafından kullanılan girişlere açıklama eklemeyi de destekler. Bu girişler iki kategoriye ayrılır:

  • Yolda, sorgu dizesinde, başlıklarda veya tanımlama bilgilerinde görülebilen parametreler.
  • İstek gövdesinin bir parçası olarak iletilen veriler

Çerçeve, yol işleyicisinin imzasını temel alarak yol, sorgu ve üst bilgi dizesindeki istek parametrelerinin türlerini otomatik olarak çıkarsar.

İstek gövdesi olarak iletilen girişlerin türünü tanımlamak için, istek işleyicisi tarafından beklenen nesne türünü ve içerik türünü tanımlamak için uzantı yöntemini kullanarak Accepts özellikleri yapılandırın. Aşağıdaki örnekte, uç nokta istek gövdesinde beklenen içerik türüne Todosahip bir nesne kabul ederapplication/xml.

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Accepts uzantı yöntemine ek olarak, Bir parametre türü, IEndpointParameterMetadataProvider arabirimini uygulayarak kendi ek açıklamasını tanımlayabilir. Örneğin, aşağıdaki Todo türü, application/xml içerik türüne sahip bir istek gövdesi gerektiren bir açıklama ekler.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

Açık bir ek açıklama sağlanmadığında, framework uç nokta işleyicisinde bir istek gövdesi parametresi varsa varsayılan istek türünü belirlemeye çalışır. Çıkarım, notu oluşturmak için aşağıdaki sezgisel yöntemleri kullanır.

  • Formdan [FromForm] özniteliği aracılığıyla okunan istek gövdesi parametreleri, multipart/form-data içerik türü ile açıklanır.
  • Diğer tüm istek gövdesi parametreleri içerik türüyle application/json açıklanır.
  • İstek gövdesi, null olabilir veya AllowEmpty özelliği FromBody özniteliğine ayarlanmışsa isteğe bağlı olarak kabul edilir.

API sürümü oluşturma desteği

En düşük API'ler, Asp.Versioning.Http paketi aracılığıyla API sürümü oluşturma desteği sunar. En düşük API'lerle sürüm oluşturma yapılandırma örnekleri API sürüm oluşturma deposunda bulunabilir.

GitHub'da ASP.NET Core OpenAPI kaynak kodu

Ek Kaynaklar

En düşük API uygulaması, Swashbuckle kullanarak yol işleyicileri için OpenAPI belirtimini açıklayabilir.

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

Aşağıdaki kod, OpenAPI desteğine sahip tipik bir ASP.NET Core uygulamasıdır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
                               Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
                                    $"{builder.Environment.ApplicationName} v1"));
}

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

app.Run();

OpenAPI açıklamasını dışla

Aşağıdaki örnekte, /skipme uç nokta openAPI açıklaması oluşturmanın dışında tutulur:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Yanıt türlerini açıklama

Aşağıdaki örnek, yanıtı özelleştirmek için yerleşik sonuç türlerini kullanır:

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

OpenAPI'ye işlem kimlikleri ekleme

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

OpenAPI açıklamasına etiket ekleme

Aşağıdaki kod bir OpenAPI gruplandırma etiketi kullanır:

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");