Swashbuckle ve ASP.NET Core kullanmaya başlayın

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

• Swashbuckle. AspNetCore. Swagger: SwaggerDocument nesneleri JSON uç noktaları olarak göstermek için Swagger nesne modeli ve ara yazılımı.

• Swashbuckle. AspNetCore. SwaggerGen: SwaggerDocument nesneleri doğrudan rotalarınız, Denetleyicilerinizden ve modellerden oluşturan bir Swagger Oluşturucu. 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 Kullanıcı arabirimi aracının gömülü bir 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.

Paket yüklemesi

Aşağıdaki yaklaşımlar ile swashbuckle eklenebilir:

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

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

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

Swagger üreticisini program. cs içindeki hizmetler koleksiyonuna ekleyin:

builder.Services.AddControllers();

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

Program. cs' de oluşturulan JSON belgesine ve Swagger Kullanıcı arabirimine hizmet veren ara yazılımı etkinleştirin:

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

Yukarıdaki kod, yalnızca geçerli ortam geliştirme olarak ayarlandıysa Swagger ara yazılımını ekler. UseSwaggerUIYöntem çağrısı statik dosya ara yazılımınısunar.

Uygulamayı başlatın ve adresine gidin https://localhost:<port>/swagger/v1/swagger.json . Uç noktaları tanımlayan oluşturulan belge, openapı belirtiminde (openapi. JSON)gösterildiği gibi görüntülenir.

Swagger Kullanıcı arabirimi adresinde bulunabilir https://localhost:<port>/swagger . Swagger Kullanıcı arabirimi aracılığıyla API 'YI keşfet ve diğer programlarda birleştirme.

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    options.RoutePrefix = string.Empty;
});

IIS veya ters proxy ile dizin kullanıyorsanız, Swagger uç noktasını, öneki kullanılarak göreli bir yol olarak ayarlayın ./ . Örneğin, ./swagger/v1/swagger.json. Kullanarak /swagger/v1/swagger.json , UYGULAMANıN URL 'nin gerçek KÖKÜNDE json dosyasını aramasını söyler (Ayrıca kullanılıyorsa rota öneki). Örneğin https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json yerine https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json kullanın.

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

Özelleştirme ve genişletme

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

API bilgisi ve açıklaması

Yöntemine geçirilen yapılandırma eylemi AddSwaggerGen Yazar, lisans ve açıklama gibi bilgiler ekler.

Program. cs' de, 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ı kullanarak OpenApiInfo , Kullanıcı arabiriminde görünen 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şımlar ile etkinleştirilebilir:

XML açıklamalarını etkinleştirmek, belgelenmemiş ortak türler ve Üyeler için hata ayıklama bilgileri sağlar. Belgelenmemiş türler ve Üyeler uyarı iletisiyle belirtilir. Örneğin, aşağıdaki ileti 1591 uyarı kodunu ihlal eder:

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

Uyarıları proje genelinde gizlemek için, proje dosyasında yoksayılacak uyarı kodlarının noktalı virgülle ayrılmış bir listesini tanımlayın. Yalnızca $(NoWarn); C# varsayılan değerlerini uygulamak için uyarı kodlarını eklemek.

Yalnızca belirli Üyeler için uyarıları gizlemek için, kodu #pragma uyarı Önişlemci yönergeleri arasına alın. Bu yaklaşım, API belgeleri aracılığıyla sunulmaması gereken kod için yararlıdır. Aşağıdaki örnekte, tüm sınıf için uyarı kodu CS1591 yok sayılır TodoContext . Uyarı kodu zorlaması sınıf tanımının kapandığına geri yüklenir. Virgülle ayrılmış bir liste ile 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 'yi yukarıdaki yönergelerle oluşturulan XML dosyasını kullanacak şekilde yapılandırın. Linux veya Windows olmayan işletim sistemleri için dosya adları ve yolları büyük/küçük harfe duyarlı olabilir. örneğin, bir TodoApi.XML dosya Windows üzerinde geçerlidir ancak centos 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, yansıma , Web API projesi ile 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, bir XML belge dosyası kullanılmadan, giriş parametrelerinin veya HTTP yöntemlerinin ve yanıt kodlarının) bir bölümü çalışır. Çoğu özellik için, yöntem özetleri ve parametrelerin ve yanıt kodlarının açıklamaları, bir XML dosyası kullanımı zorunludur.

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

/// <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 öğesinin iç metnini görüntüler <summary> :

Kullanıcı arabirimi, oluşturulan JSON şeması tarafından çalıştırılır:

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

<remarks> Create Eylem yöntemi belgelerine bir öğesi ekleyin. Öğesinde belirtilen bilgileri tamamlar <summary> ve daha sağlam bir Swagger Kullanıcı arabirimi sağlar. <remarks>Öğe içeriği metin, JSON veya XML içerebilir.

/// <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 UI geliştirmelerini göz unutmayın:

Veri açıklamaları

Swagger UI bileşenlerinin sürücüsüne yardımcı olmak için modeli System.ComponentModel.DataAnnotations ad alanı içinde bulunan özniteliklerle işaretleme.

özniteliğini [Required] sınıfının Name ö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 alınan JSON ş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
    }
},

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

[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çilidir:

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'si kullanan geliştiriciler en çok döndürülen yanıt türleri ve hata — kodlarıyla (standart olmayanlar) ilgilidir. Yanıt türleri ve hata kodları XML açıklamalarında ve veri açıklamalarında yer alır.

Eylem, Create başarı durumunda bir HTTP 201 durum kodu döndürür. Gönderilen istek gövdesi null olduğunda HTTP 400 durum kodu döndürülür. Swagger kullanıcı arabiriminde düzgün 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ı net bir şekilde belgelemektedir:

Kural, ile ayrı eylemleri açıkça dekore etmek için bir alternatif olarak [ProducesResponseType] kullanılabilir. Daha fazla bilgi için bkz. Web API'si kuralları kullanma.

[ProducesResponseType] Swashbuckle.AspNetCore.Annotations paketi, süslemeyi desteklemek için yanıt, şema ve parametre meta verilerini etkinleştirmeye ve zenginleştirmeye olanak sağlayan uzantılar sunar.

Kullanıcı arabirimini özelleştirme

Varsayılan kullanıcı arabirimi hem işlevsel hem de kullanılabilir durumdadır. Ancak API belge sayfaları markanızı veya temanızı temsil ediyor olabilir. Swashbuckle bileşenlerinin markasını eklemek için statik dosyaları barındırmak ve bu dosyaları barındırmak için klasör yapısını eklemek gerekir.

Statik Dosya Ara Yazılımları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:

app.UseSwaggerUI(options =>
{
    options.InjectStylesheet("/swagger-ui/custom.css");
});

Ek kaynaklar

• Microsoft Learn: Swagger belgeleriyle API'nin geliştirici deneyimini geliştirme

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

• Swashbuckle.AspNetCore.Swagger:Nesneleri JSON uç noktaları olarak ortaya çıkarmak için bir Swagger nesne SwaggerDocument modeli ve ara yazılımı.

• Swashbuckle.AspNetCore.SwaggerGen:Doğrudan yollarınız, denetleyicileriniz ve modelleriniz tarafından nesneleri yapılandıran bir Swagger SwaggerDocument oluşturucu. 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: SwaggerUI aracının eklenmiş bir 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.

Paket yüklemesi

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

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

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

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

Swagger oluşturucusünü yönteminde hizmetler koleksiyonuna Startup.ConfigureServices ekleyin:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

Startup.Configureyönteminde, oluşturulan JSON belgesine ve Swagger kullanıcı arabirimine hizmet etmek için ara yazılımı etkinleştirin:

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
    app.UseSwaggerUI();

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Yukarıdaki yöntem UseSwaggerUI çağrısı Statik Dosya Ara Yazılım'ı sağlar. .NET Framework veya .NET Core 1.x'i hedeflerse, projeye Microsoft.AspNetCore.StaticFiles NuGet paketini ekleyin.

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

Swagger ui'sı şu şekilde http://localhost:<port>/swagger bulunabilir: . Swagger UI aracılığıyla API'yi keşfedin ve diğer programlara dahil edin.

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

IIS veya ters ara sunucu ile dizinler kullanıyorsanız, ön ekini kullanarak Swagger uç noktasını göreli bir yola ./ ayarlayın. Örneğin, ./swagger/v1/swagger.json. kullanmak, uygulamaya URL'nin gerçek kökünde JSON dosyasını aramasını (kullanılıyorsa yol ön /swagger/v1/swagger.json eki) ile birlikte aramasını sağlar. Örneğin http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json yerine http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json kullanın.

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger(c =>
    {
        c.SerializeAsV2 = true;
    });

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Özelleştirme ve genişletme

Swagger, nesne modelini belgeleye ve kullanıcı arabirimini temanıza uygun şekilde özelleştirmek için seçenekler sağlar.

sınıfında, Startup aşağıdaki ad alanlarını ekleyin:

using System;
using System.Reflection;
using System.IO;

API bilgileri ve açıklaması

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

sınıfında, Startup sınıfını kullanmak için aşağıdaki ad alanını içeri OpenApiInfo aktarın:

using Microsoft.OpenApi.Models;

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

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });
});

Swagger UI sürümün bilgilerini görüntüler:

XML açıklamaları

XML yorumları aşağıdaki yaklaşımlarla etkinleştirilebilir:

XML açıklamalarını etkinleştirmek, belgelenmemiş ortak türler ve Üyeler için hata ayıklama bilgileri sağlar. Belgelenmemiş türler ve Üyeler uyarı iletisiyle belirtilir. Örneğin, aşağıdaki ileti 1591 uyarı kodunu ihlal eder:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Uyarıları proje genelinde gizlemek için, proje dosyasında yoksayılacak uyarı kodlarının noktalı virgülle ayrılmış bir listesini tanımlayın. Yalnızca $(NoWarn); C# varsayılan değerlerini uygulamak için uyarı kodlarını eklemek.

Yalnızca belirli Üyeler için uyarıları gizlemek için, kodu #pragma uyarı Önişlemci yönergeleri arasına alın. Bu yaklaşım, API belgeleri aracılığıyla sunulmaması gereken kod için yararlıdır. Aşağıdaki örnekte, tüm sınıf için uyarı kodu CS1591 yok sayılır Program . Uyarı kodu zorlaması sınıf tanımının kapandığına geri yüklenir. Virgülle ayrılmış bir liste ile birden çok uyarı kodu belirtin.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#pragma warning restore CS1591
}

Swagger 'yi yukarıdaki yönergelerle oluşturulan XML dosyasını kullanacak şekilde yapılandırın. Linux veya Windows olmayan işletim sistemleri için dosya adları ve yolları büyük/küçük harfe duyarlı olabilir. örneğin, bir TodoApi.XML dosya Windows üzerinde geçerlidir ancak centos değildir.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Yukarıdaki kodda, yansıma , Web API projesi ile 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, bir XML belge dosyası kullanılmadan, giriş parametrelerinin veya HTTP yöntemlerinin ve yanıt kodlarının) bir bölümü çalışır. Çoğu özellik için, yöntem özetleri ve parametrelerin ve yanıt kodlarının açıklamaları, bir XML dosyası kullanımı zorunludur.

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

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

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

Kullanıcı arabirimi, oluşturulan JSON şeması tarafından çalıştırılır:

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

<remarks> Create Eylem yöntemi belgelerine bir öğesi ekleyin. Öğesinde belirtilen bilgileri tamamlar <summary> ve daha sağlam bir Swagger Kullanıcı arabirimi sağlar. <remarks>Öğe içeriği metin, JSON veya XML içerebilir.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Bu ek açıklamalarla UI geliştirmelerini göz unutmayın:

Veri açıklamaları

Swagger Kullanıcı Arabirimi bileşenlerini sağlamaya yardımcı olmak için System. ComponentModel. Dataaçıklamalarda ad alanında bulunan öznitelikleri olan modeli işaretleyin.

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

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

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

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

Bu özniteliğin varlığı, Kullanıcı arabirimi davranışını değiştirir ve temel alınan JSON şemasını değiştirir:

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

[Produces("application/json")]ÖZNITELIĞI API denetleyicisine ekleyin. Amaç, denetleyicinin eylemlerinin bir uygulama/JSON yanıt içerik türünü desteklediğini bildirsağlamaktır:

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

Yanıt Içerik türü açılan liste, denetleyicinin al eylemleri için varsayılan olarak bu içerik türünü seçer:

Web API 'sindeki veri ek açıklamaların kullanımı arttıkça, UI ve API Yardım sayfaları daha açıklayıcı ve yararlı hale gelir.

Yanıt türlerini açıkla

Bir Web API 'SI kullanan geliştiriciler, — özellikle yanıt türleri ve hata kodları (Standart değilse) döndürülmesiyle ilgilidir. Yanıt türleri ve hata kodları XML açıklamaları ve veri ek açıklamalarında gösterilir.

CreateEylem başarılı olduğunda BIR HTTP 201 durum kodu döndürür. Postalanan istek gövdesi null olduğunda bir HTTP 400 durum kodu döndürülür. Swagger Kullanıcı arabiriminde doğru belgeler olmadan, tüketici beklenen bu sonuçlar hakkında bilgi sahibi yoktur. Aşağıdaki örneğe vurgulanan satırları ekleyerek bu sorunu giderebilirsiniz:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

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

ASP.NET Core 2,2 veya üzeri sürümlerde kurallar, ile tek tek eylemleri açıkça dekorasyon alternatifi olarak kullanılabilir [ProducesResponseType] . Daha fazla bilgi için bkz. Web API'si kuralları kullanma.

Deseni desteklemek için [ProducesResponseType] , swashbuckle. Aspnetcore. açıklamalarda paketi, yanıt, şema ve parametre meta verilerini etkinleştirmek ve zenginleştirmek için uzantılar sağlar.

Kullanıcı arabirimini özelleştirme

Varsayılan Kullanıcı arabirimi hem işlevsel hem de edileni. Ancak, API belge sayfaları markanızı veya temanızı temsil etmelidir. Marka, swashbuckle bileşenleri, statik dosyalara ve bu dosyaları barındırmak için klasör yapısını oluşturmaya yönelik kaynakların eklenmesini gerektirir.

.NET Framework veya .net Core 1. x 'i hedefliyorsanız, Microsoft. aspnetcore. staticfiles NuGet paketini projeye ekleyin:

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />

önceki NuGet paketi .net Core 2. x hedefleniyorsa ve metapackagekullanılıyorsa zaten yüklüdür.

Statik dosya ara yazılımını etkinleştir:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.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:

app.UseSwaggerUI(c =>
{
     c.InjectStylesheet("/swagger-ui/custom.css");
}

Ek kaynaklar

• Microsoft Learn: Swagger belgeleriyle bir API 'nin geliştirici deneyimini geliştirme