Swashbuckle ve ASP.NET Core ile çalışmaya başlama

Not

Swashbuckle ile derleme zamanı OpenAPI belgesi oluşturma işlemi .NET 8 ve sonraki sürümlerde desteklenmez. Desteklenen bir derleme zamanı alternatifi için Swagger / OpenAPI ile Core web API'si belgelerine ASP.NET bakın. Çalışma zamanı belge oluşturma işlemi .NET 8'de hala desteklenmektedir.

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

• Swashbuckle.AspNetCore.Swagger: nesneleri ON uç noktaları olarak JSkullanıma sunan SwaggerDocument bir Swagger nesne modeli ve ara yazılımı.

• Swashbuckle.AspNetCore.SwaggerGen: doğrudan rotalarınızdan, denetleyicilerinizden ve modellerinizden nesneler oluşturan SwaggerDocument bir Swagger oluşturucu. Genellikle Swagger uç noktası ara yazılımıyla birlikte Swagger JSON'ı otomatik olarak kullanıma sunar.

• Swashbuckle.AspNetCore.SwaggerUI: Swagger UI aracının ekli sürümü. Swagger JSON'ı yorumlayarak web API'sinin işlevselliğini açıklamaya yönelik zengin, özelleştirilebilir bir deneyim oluşturur. Genel yöntemler için yerleşik test kuluçkaları içerir.

Paket yükleme

Swashbuckle aşağıdaki yaklaşımlarla eklenebilir:

Visual Studio

• Paket Yöneticisi Konsolu penceresinden:

  • Diğer Pencereleri> Görüntüle>Paket Yöneticisi Konsolu'na gidin

  • Dosyanın bulunduğu dizine .csproj gidin

  • Şu kodu yürütün:

    Install-Package Swashbuckle.AspNetCore -Version 6.5.0
    

• NuGet Paketlerini Yönet iletişim kutusundan:

  • Çözüm Gezgini> NuGet Paketlerini Yönet'te projeye sağ tıklayın
  • Paket kaynağını "nuget.org" olarak ayarlayın
  • "Ön sürümü dahil et" seçeneğinin etkinleştirildiğinden emin olun
  • Arama kutusuna "Swashbuckle.AspNetCore" yazın
  • Gözat sekmesinden en son "Swashbuckle.AspNetCore" paketini seçin ve Yükle'ye tıklayın

Mac için Visual Studio

• Çözüm Bölmesi>Paket Ekle'de Paketler klasörüne sağ tıklayın...
• Paket Ekle penceresinin Kaynak açılan menüsünü "nuget.org" olarak ayarlayın
• "Yayın öncesi paketleri göster" seçeneğinin etkinleştirildiğinden emin olun
• Arama kutusuna "Swashbuckle.AspNetCore" yazın
• Sonuçlar bölmesinden en son "Swashbuckle.AspNetCore" paketini seçin ve Paket Ekle'ye tıklayın

Visual Studio Code

Tümleşik Terminal'den aşağıdaki komutu çalıştırın:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.5.0

.NET Core CLI

Şu komutu çalıştırın:

dotnet add TodoApi.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.AddControllers();

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

Önceki örnekte gösterilen çağrısı AddEndpointsApiExplorer yalnızca minimum API'ler için gereklidir. Daha fazla bilgi için bu StackOverflow gönderisini inceleyin.

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

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

Yukarıdaki kod, Swagger ara yazılımını yalnızca geçerli ortam Geliştirme olarak ayarlandıysa ekler. Yöntem UseSwaggerUI çağrısı, Swagger UI aracının katıştırılmış bir sürümünü etkinleştirir.

Uygulamayı başlatın ve adresine https://localhost:<port>/swagger/v1/swagger.jsongidin. Uç noktaları açıklayan oluşturulan belge OpenAPI belirtiminde (openapi.json) gösterildiği gibi görünür.

Swagger kullanıcı arabirimine adresinden https://localhost:<port>/swaggerulaşabilirsiniz. Swagger kullanıcı arabirimi aracılığıyla API'yi keşfedin ve diğer programlara ekleyin.

İpucu

Swagger kullanıcı arabirimini uygulamanın kökünde ()https://localhost:<port>/ sunmak için özelliğini boş bir dize olarak ayarlayın RoutePrefix :

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

DIZINleri IIS veya ters ara sunucu ile kullanıyorsanız, ön ekini kullanarak ./ Swagger uç noktasını göreli bir yola ayarlayın. Örneğin, ./swagger/v1/swagger.json. komutunun kullanılması /swagger/v1/swagger.json , uygulamaya URL'nin gerçek kökünde ON dosyasını (kullanılıyorsa yol ön ekinin yanı sıra) arama JStalimatı verir. Örneğin, yerine https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.jsonkullanınhttps://localhost:<port>/<route_prefix>/swagger/v1/swagger.json.

Not

Varsayılan olarak, Swashbuckle belirtimin 3.0 sürümünde Swagger JSON oluşturur ve kullanıma sunar; resmi olarak OpenAPI Belirtimi olarak adlandırılır. Geriye dönük uyumluluğu desteklemek için bunun yerine ON'ı 2.0 biçiminde açık JSduruma getirebilirsiniz. Bu 2.0 biçimi, şu anda OpenAPI sürüm 2.0'ı destekleyen Microsoft Power Apps ve Microsoft Flow gibi tümleştirmeler için önemlidir. 2.0 biçimini kabul etmek için özelliğini içinde Program.csayarlayınSerializeAsV2:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

'ı özelleştirme ve uzatma

Swagger, nesne modelini belgeleme ve kullanıcı arabirimini temanızla eşleşecek şekilde özelleştirme seçenekleri sağlar.

API bilgileri ve açıklaması

yöntemine AddSwaggerGen geçirilen yapılandırma eylemi yazar, lisans ve açıklama gibi bilgileri ekler.

içinde Program.cs, sınıfını kullanmak için aşağıdaki ad alanını içeri aktarın OpenApiInfo :

using Microsoft.OpenApi.Models;

sınıfını OpenApiInfo kullanarak kullanıcı arabiriminde görüntülenen bilgileri değiştirin:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

Swagger kullanıcı arabirimi sürümün bilgilerini görüntüler:

XML açıklamaları

XML açıklamaları aşağıdaki yaklaşımlarla etkinleştirilebilir:

Visual Studio

• Çözüm Gezgini'da projeye sağ tıklayın ve öğesini seçinEdit <project_name>.csproj.
• Dosyaya .csproj GenerateDocumentationFile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Mac için Visual Studio

• Çözüm Bölmesi'nden denetime basın ve proje adına tıklayın. Araçlar>Dosya Düzenle'ye gidin.
• Dosyaya .csproj GenerateDocumentationFile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Dosyaya .csproj GenerateDocumentationFile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

.NET Core CLI

Dosyaya .csproj GenerateDocumentationFile ekleyin:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

XML açıklamalarının etkinleştirilmesi, belgelenmemiş genel türler ve üyeler için hata ayıklama bilgileri sağlar. Belgelenmemiş türler ve üyeler uyarı iletisiyle gösterilir. Örneğin, aşağıdaki ileti uyarı kodu 1591'in ihlalini gösterir:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Proje genelinde uyarıları engellemek için proje dosyasında yoksaymak üzere noktalı virgülle ayrılmış bir uyarı kodu listesi tanımlayın. Uyarı kodlarının eklenmesi $(NoWarn); C# varsayılan değerlerini de uygular.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Yalnızca belirli üyelere yönelik uyarıları engellemek için kodu #pragma uyarı önişlemci yönergeleri içine alın. Bu yaklaşım, API belgeleri aracılığıyla kullanıma sunulmaması gereken kodlar için kullanışlıdır. Aşağıdaki örnekte, cs1591 uyarı kodu sınıfın tamamı TodoContext için yoksayılır. Uyarı kodunun uygulanması, sınıf tanımının kapanışında geri yüklenir. Virgülle ayrılmış bir listeyle birden çok uyarı kodu belirtin.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Swagger'ı, önceki yönergelerle oluşturulan XML dosyasını kullanacak şekilde yapılandırın. Linux veya Windows dışı işletim sistemlerinde dosya adları ve yollar büyük/küçük harfe duyarlı olabilir. Örneğin, bir TodoApi.XML dosya Windows'ta geçerlidir ancak Ubuntu'da geçerli değildir.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Yukarıdaki kodda Düşünceler ion, web API'si projesiyle eşleşen bir XML dosya adı oluşturmak için kullanılır. AppContext.BaseDirectory özelliği, XML dosyasının yolunu oluşturmak için kullanılır. Bazı Swagger özellikleri (örneğin, giriş parametrelerinin şeması veya http yöntemleri ve ilgili özniteliklerden gelen yanıt kodları) XML belge dosyası kullanılmadan çalışır. Yöntem özetleri ve parametrelerin ve yanıt kodlarının açıklamaları gibi çoğu özellik için XML dosyasının kullanılması zorunludur.

Bir eyleme üç eğik çizgiyle açıklama eklediğinizde bölüm üst bilgisine açıklama eklenir ve Swagger UI geliştirilir. Eylemin Delete üzerine bir< özet> öğesi ekleyin:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

Swagger kullanıcı arabirimi, önceki kodun <summary> öğesinin iç metnini görüntüler:

Kullanıcı arabirimi, oluşturulan JSON şeması tarafından yönlendirilir:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Eylem yöntemi belgelerine Create bir <açıklamalar> öğesi ekleyin. öğesinde <summary> belirtilen bilgileri tamamlar ve daha sağlam bir Swagger kullanıcı arabirimi sağlar. <remarks> Öğe içeriği metin, JSON veya XML'lerden oluşabilir.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Bu ek açıklamalarla kullanıcı arabirimi geliştirmelerine dikkat edin:

Veri açıklamaları

Swagger KULLANıCı arabirimi bileşenlerinin sürücüye yardımcı olması için modeli ad alanında System.ComponentModel.DataAnnotations bulunan özniteliklerle işaretleyin.

özniteliğini [Required]Name sınıfının özelliğine TodoItem ekleyin:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Bu özniteliğin varlığı kullanıcı arabirimi davranışını değiştirir ve temel on JSşemasını değiştirir:

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

özniteliğini [Produces("application/json")] API denetleyicisine ekleyin. Amacı, denetleyicinin eylemlerinin bir uygulama/json yanıt içerik türünü desteklediğini bildirmektir:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

Medya türü açılan listesinde, denetleyicinin GET eylemleri için varsayılan olarak bu içerik türü seçilir:

Web API'sinde veri ek açıklamalarının kullanımı arttıkça, kullanıcı arabirimi ve API yardım sayfaları daha açıklayıcı ve kullanışlı hale gelir.

Yanıt türlerini açıklama

Web API'sini kullanan geliştiriciler, özellikle yanıt türleri ve hata kodları (standart değilse) olmak üzere döndürülen öğelerle ilgilenir. Yanıt türleri ve hata kodları XML açıklamalarında ve veri ek açıklamalarında belirtilir.

Eylem, Create başarılı olduğunda bir HTTP 201 durum kodu döndürür. Gönderilen istek gövdesi null olduğunda bir HTTP 400 durum kodu döndürülür. Swagger kullanıcı arabiriminde uygun belgeler olmadan, tüketici bu beklenen sonuçlar hakkında bilgi sahibi değildir. Aşağıdaki örnekte vurgulanan satırları ekleyerek bu sorunu düzeltin:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Swagger kullanıcı arabirimi artık beklenen HTTP yanıt kodlarını açıkça belgelemektedir:

Kurallar, ile [ProducesResponseType]tek tek eylemleri açıkça dekore etmek için alternatif olarak kullanılabilir. Daha fazla bilgi için bkz . Web API kurallarını kullanma.

Swashbuckle.AspNetCore.Annotations paketi, dekorasyonu [ProducesResponseType] desteklemek için yanıt, şema ve parametre meta verilerini etkinleştirmek ve zenginleştirmek için uzantılar sunar.

Kullanıcı arabirimini özelleştirme

Varsayılan kullanıcı arabirimi hem işlevsel hem de sunuludur. Ancak, API belge sayfaları markanızı veya temanızı temsil etmelidir. Swashbuckle bileşenlerinin markalanması için statik dosyalara hizmet vermek için kaynakların eklenmesi ve bu dosyaları barındıracak klasör yapısının oluşturulması gerekir.

Statik Dosya Ara Yazılımını Etkinleştir:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Ek CSS stil sayfaları eklemek için, bunları projenin wwwroot klasörüne ekleyin ve ara yazılım seçeneklerinde göreli yolu belirtin:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Ek kaynaklar

• Örnek kodu görüntüleme veya indirme (indirme)
• Swagger kayıtlardaki açıklamaları veya öznitelikleri tanımıyor
• Swagger belgeleriyle API'nin geliştirici deneyimini geliştirme