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 uygulamadaki bir uç nokta üzerinden bunlara 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 -IncludePrerelease

OpenAPI belge oluşturmayı yapılandırma

Aşağıdaki kod:

  • OpenAPI hizmetleri ekler.
  • OpenAPI belgesini JSON biçiminde görüntülemek için uç noktayı etkinleştirir.
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

Belge adı, çağrıya AddOpenApi 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 parametre bağımsız değişkeni olarak sağlanır. Aşağıdaki istekler ve internal belgelerini çözümlerv1.

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, çağrı MapOpenApi yoluyla kaydedilen OpenAPI uç noktası belgeyi /openapi/{documentName}.json uç noktada 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. yolunun veya sorgunun sağlanmaması documentName 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();

app.MapOpenApi()
    .CacheOutput();

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

app.Run();

Derleme zamanında OpenAPI belgeleri oluşturma

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

Yükleme sonrasında, bu paket derleme sırasında uygulamayla ilişkili Open API belgelerini otomatik olarak oluşturur ve bunları uygulamanın çıkış dizinine doldurur.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Derleme 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 çözümlenir. 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 özelliğinde bağımsız değişkenini --file-name OpenApiGenerateDocumentsOptions ayarlayın.

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

Oluşturulacak OpenAPI belgesini seçme

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

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

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

Derleme zamanı OpenAPI belge oluşturma işlevi, uygulamanın giriş noktasını eylemsiz bir sunucu uygulamasıyla başlatarak arka planda çalışır. OpenAPI belgesindeki tüm bilgiler statik olarak çözümlenemediğinden, doğru OpenAPI belgeleri oluşturmak için bu bir gereksinimdir. Uygulamanın giriş noktası çağrıldığından, uygulamaların başlangıcındaki tüm mantık çağrılır. Bu, HIZMETLERI DI kapsayıcısına ekleyen veya yapılandırmadan okuyan kodu içerir. Bazı senaryolarda, uygulamanın giriş noktası derleme zamanı belge oluşturma işleminden çağrılırken çalışacak kod yollarının kısıtlanması gerekir. Bu senaryolar şunlardır:

  • Bazı yapılandırma dizelerinden 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, aşağıdaki gibi giriş derlemesinin denetiminin arkasına koşullanabilir:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

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

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 , API Gezgini tarafından paketten Microsoft.AspNetCore.OpenApi üretilenlerle oluşturulan varsayılan ek açıklamaları geçersiz kılar.
  • UseSwaggerSwagger ara yazılımını ekler.
  • 'UseSwaggerUI', Swagger UI aracının eklenmiş bir sürümünü etkinleştirir.
  • WithNameIEndpointNameMetadata: 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 Microsoft.AspNetCore.OpenApiSwashbuckle.AspNetCore 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.

Aracılığıyla uç noktalara OpenAPI ek açıklamaları ekleme WithOpenApi

Uç noktada çağrılması WithOpenApi , uç noktanın meta verilerine eklenir. Bu meta veriler şu şekilde olabilir:

  • Swashbuckle.AspNetCore gibi üçüncü taraf paketlerde kullanılır.
  • 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();

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

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, uç nokta üzerindeki WithTags uzantısı yöntemi istenen etiketlerle çağrılarak bir işleme eklenebilir.

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

Alternatif olarak, uzantısı yöntemi aracılığıyla OpenAPI ek açıklamasında WithOpenApi listesi OpenApiTags 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ı, uzantı yöntemi çağrılarak WithOpenApi eklenebilir. Aşağıdaki kodda özetler doğrudan OpenAPI ek açıklamasında 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 ek açıklamasında özelliğini ayarlayın Deprecated .

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 meta veri eklemek Produces 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, içerik türüne sahip durum kodu altında 200 bir yanıtla application/json uç noktaya otomatik olarak açıklama ekler.

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

için yanıtları ayarlama ProblemDetails

ProblemDetails yanıtı döndürebilecek uç noktalar için yanıt türünü ayarlarken, uzantı yöntemi ProducesValidationProblemveya TypedResults.Problem uç noktanın ProducesProblem meta verilerine uygun ek açıklamayı eklemek için kullanılabilir. ve ProducesValidationProblem uzantısı yöntemlerinin ProducesProblem .NET 8 ve önceki sürümlerde yol gruplarıyla kullanılamadığı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 imzada ve TypedResults işleyicinin gövdesinde kullanınResults<TResult1,TResult2,TResultN>:

    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 , yol işleyicisinin birden çok IResultuygulayan somut tür döndürdüğünü ve uygulayan IEndpointMetadataProvider türlerden herhangi birinin uç noktanın meta verilerine katkıda bulunacağını bildirir.

    Birleşim türleri örtük atama işleçleri 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. Derleme hatasıyla sonuçlanması için genel bağımsız değişkenlerden biri olarak bildirlenmemiş bir tür döndürülmeye Results<TResult1,TResult2,TResultN> çalışılıyor.

İ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, üst bilgilerde veya tanımlama bilgilerinde görünen 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 application/xmlsahip bir nesne kabul ederTodo.

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

Uzantı yöntemine Accepts ek olarak, parametre türü arabirimini uygulayarak IEndpointParameterMetadataProvider kendi ek açıklamasını açıklayabilir. Örneğin, aşağıdaki Todo tür içerik türüne sahip bir istek gövdesi gerektiren bir application/xml ek 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ğlanmayan çerçeve, uç nokta işleyicisinde bir istek gövdesi parametresi varsa varsayılan istek türünü belirlemeye çalışır. Çıkarım, ek açıklamayı oluşturmak için aşağıdaki buluşsal yöntemleri kullanır:

  • Özniteliği aracılığıyla [FromForm] bir formdan okunan istek gövdesi parametreleri içerik türüyle multipart/form-data 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 atanabilirse veya özellik özniteliğinde FromBody ayarlandıysa AllowEmpty 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");