Swashbuckle kullanarak API'yi belgele

Tamamlandı

Swashbuckle, ASP.NET Web API projeleri için otomatik olarak Swagger belgeleri oluşturmanın bir yolunu sağlayan bir NuGet paketidir. Swagger, geliştiricilerin RESTful API'lerini tasarlamalarına, oluşturmalarına, belgelendirmelerine ve kullanmalarına yardımcı olan bir araçtır. Swashbuckle ile, API uç noktalarınızı, parametrelerinizi ve yanıtlarınızı açıklayan özniteliklerle kodunuza açıklama ekleyerek Web API projenize kolayca Swagger belgeleri ekleyebilirsiniz. Swashbuckle daha sonra bu bilgileri kullanarak etkileşimli API belgeleri, istemci SDK'ları ve daha fazlasını oluşturmak için kullanılabilecek bir Swagger JSON dosyası oluşturur.

Swashbuckle'ın üç temel bileşeni vardır:

• Swashbuckle.AspNetCore.Swagger: SwaggerDocument nesnelerini JSON uç noktaları olarak kullanıma sunan bir Swagger nesne modeli ve ara yazılımı.

• Swashbuckle.AspNetCore.SwaggerGen: Yollarınızdan, denetleyicilerinizden ve modellerinizden doğrudan SwaggerDocument nesneleri oluşturan bir Swagger üreticisi. Bu genellikle Swagger JSON uç noktasını otomatik olarak kullanıma sunmak için Swagger uç noktası ara katmanıyla birlikte kullanılır.

• Swashbuckle.AspNetCore.SwaggerUI: Swagger UI aracının ekli sürümü. Swagger JSON uç noktasını yorumlayarak web API'sinin işlevlerini tanımlayan zengin ve özelleştirilebilir bir deneyim oluşturur. Genel yöntemler için yerleşik test kuluçkaları içerir.

Aşağıdaki dotnet add komut Swashbuckle NuGet paketini yükler:

dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0

Swagger ara yazılımı ekleme ve yapılandırma

Swagger oluşturucuyu içindeki Program.cshizmetler koleksiyonuna ekleyin.

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

Not

Önceki örnekte gösterilen çağrısı AddEndpointsApiExplorer yalnızca minimum API'ler için gereklidir.

Oluşturulan JSON belgesine ve Swagger kullanıcı arabirimine hizmet sağlamak için ara yazılımı da içinde Program.csetkinleştirin:

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

Swagger kullanıcı arabirimi için varsayılan uç noktadır http:<hostname>:<port>/swagger.

Not

SwaggerUI, geliştirme ortamınızda çok yararlıdır. Üretimde etkinleştirilebilir, ancak bunu yapmadan önce belirli uygulamanız için güvenlik gereksinimlerini dikkate almanız gerekir.

Swagger belgelerini özelleştirme ve genişletme

Swagger, nesne modelini belgeleme ve kullanıcı arabirimini özelleştirme seçenekleri sağlar. yöntemine AddSwaggerGen geçirilen yapılandırma eylemi, sınıfı aracılığıyla OpenApiInfo ek bilgiler içerebilir.

Aşağıdaki kod örneği, API belgelerinde görüntülenecek bilgilerin nasıl ekleneceğini gösterir.

// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Fruit API",
        Description = "API for managing a list of fruit their stock status.",
        TermsOfService = new Uri("https://example.com/terms")
    });
});

Swagger kullanıcı arabirimi sürümü ve eklenen bilgileri görüntüler:

SEÇENEĞIyle .WithTags API'nizdeki işlemleri gruplandırabilirsiniz. Ayrıca, seçeneğini kullanarak işlemi .WithSummary açıklayan açıklayıcı metin de ekleyebilirsiniz. Aşağıdaki örnek kod, POST işlemini hem .WithTags grubu hem de meyve grubunda gruplandırmak için kullanıldığını göstermektedir. Ayrıca, seçeneğinde .WithSummary belirtilen özeti işleme ekler.

app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
    db.Fruits.Add(fruit);
    await db.SaveChangesAsync();

    return Results.Created($"/{fruit.Id}", fruit);
})
    .Produces<Fruit>(201)
    .WithTags("post", "fruits")
    .WithSummary("Create a new fruit");

Swagger kullanıcı arabirimi, belirtilen gruplandırma ve özet açıklamasını görüntüler.