Minimum API uygulamalarında OpenAPI desteği

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.

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.
• API'yi tanımlamak için Swagger kullanıcı arabiriminde veya 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:

• Uç nokta üzerindeki Produces uzantı yöntemi aracılığıyla
• Yol işleyicisinde ProducesResponseType özniteliği aracılığıyla
• Yol işleyicisinden döndürerek TypedResults

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 veya TypedResults.Problem uç noktanın ProducesProblem meta verilerine uygun ek açıklamayı eklemek için kullanılabilir.

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

• WithOpenApi
• OpenApiGenerator

Ek Kaynaklar

• Minimum API'lerde kimlik doğrulaması ve yetkilendirme