Basit bir veri temelli CRUD mikro hizmeti oluşturma

  • Makale

İpucu

Bu içerik, .NET Docs'ta veya çevrimdışı olarak okunabilen ücretsiz indirilebilir bir PDF olarak sağlanan Kapsayıcılı .NET Uygulamaları için .NET Mikro Hizmet Mimarisi e-Kitabı'ndan bir alıntıdır.

PDF'i indirin

Kapsayıcılı .NET Uygulamaları için .NET Mikro Hizmetler Mimarisi eKitap kapak küçük resmi.

Bu bölümde, bir veri kaynağında oluşturma, okuma, güncelleştirme ve silme (CRUD) işlemleri gerçekleştiren basit bir mikro hizmetin nasıl oluşturulacağı açıklanmıştır.

Basit bir CRUD mikro hizmeti tasarlama

Tasarım açısından bakıldığında, bu tür kapsayıcılı mikro hizmet çok basittir. Belki de çözülmesi gereken sorun basittir veya belki de uygulama yalnızca bir kavram kanıtıdır.

Basit bir CRUD mikro hizmet iç tasarım deseni gösteren diyagram.

Şekil 6-4. Basit CRUD mikro hizmetleri için iç tasarım

Bu tür basit veri sürücüsü hizmetine örnek olarak eShopOnContainers örnek uygulamasından katalog mikro hizmeti örnektir. Bu hizmet türü, tüm işlevlerini veri modeli, iş mantığı ve veri erişim kodu için sınıflar içeren tek bir ASP.NET Core Web API projesinde uygular. Ayrıca ilgili verilerini SQL Server'da çalışan bir veritabanında (geliştirme/test amacıyla başka bir kapsayıcı olarak) depolar, ancak Şekil 6-5'te gösterildiği gibi herhangi bir normal SQL Server konağı da olabilir.

Veri temelli/CRUD mikro hizmet kapsayıcısı gösteren diyagram.

Şekil 6-5. Basit veri temelli/CRUD mikro hizmet tasarımı

Önceki diyagramda, aynı Docker ana bilgisayarında bulunabilen veya olmayan Katalog veritabanını içeren mantıksal Katalog mikro hizmeti gösterilmektedir. Veritabanının aynı Docker ana bilgisayarında olması geliştirme için iyi olabilir, ancak üretim için iyi olmayabilir. Bu tür bir hizmet geliştirirken yalnızca ASP.NET Core'a ve Entity Framework Core gibi bir veri erişim API'sine veya ORM'ye ihtiyacınız vardır. Swagger meta verilerini Swashbuckle aracılığıyla otomatik olarak oluşturarak sonraki bölümde açıklandığı gibi hizmetinizin sunduğu özelliklerin açıklamasını da sağlayabilirsiniz.

Docker kapsayıcısı içinde SQL Server gibi bir veritabanı sunucusu çalıştırmanın geliştirme ortamları için harika olduğunu unutmayın, çünkü bulutta veya şirket içinde veritabanı sağlamaya gerek kalmadan tüm bağımlılıklarınızı çalışır duruma getirmeniz gerekir. Tümleştirme testleri çalıştırılırken bu yaklaşım kullanışlıdır. Ancak, genellikle bu yaklaşımla yüksek kullanılabilirlik elde etmediğinizden, üretim ortamlarında kapsayıcıda veritabanı sunucusu çalıştırılması önerilmez. Azure'daki bir üretim ortamı için, Azure SQL DB'yi veya yüksek kullanılabilirlik ve yüksek ölçeklenebilirlik sağlayabilen başka bir veritabanı teknolojisini kullanmanız önerilir. Örneğin, NoSQL yaklaşımı için CosmosDB'yi seçebilirsiniz.

Son olarak, Dockerfile ve docker-compose.yml meta veri dosyalarını düzenleyerek, bu kapsayıcının görüntüsünün nasıl oluşturulacağını, hangi temel görüntüyü kullanacağını ve iç ve dış adlar ve TCP bağlantı noktaları gibi tasarım ayarlarını yapılandırabilirsiniz.

ASP.NET Core ile basit bir CRUD mikro hizmeti uygulama

.NET ve Visual Studio kullanarak basit bir CRUD mikro hizmeti uygulamak için, Şekil 6-6'da gösterildiği gibi basit bir ASP.NET Core Web API projesi oluşturarak (Linux Docker ana bilgisayarında çalışabilmesi için .NET üzerinde çalışır).

Projenin kurulumunu gösteren Visual Studios'un ekran görüntüsü.

Şekil 6-6. Visual Studio 2019'da ASP.NET Core Web API projesi oluşturma

ASP.NET Core Web API Projesi oluşturmak için önce bir ASP.NET Core Web Uygulaması seçin ve ardından API türünü seçin. Projeyi oluşturduktan sonra, Entity Framework API'sini veya diğer API'yi kullanarak MVC denetleyicilerinizi diğer web API'leri projelerinde olduğu gibi uygulayabilirsiniz. Yeni bir Web API'si projesinde, bu mikro hizmete sahip olduğunuz tek bağımlılığın ASP.NET Core'un kendisinde olduğunu görebilirsiniz. Dahili olarak, Microsoft.AspNetCore.All bağımlılığında, Şekil 6-7'de gösterildiği gibi Entity Framework ve diğer birçok .NET NuGet paketine başvurur.

Catalog.Api'nin NuGet bağımlılıklarını gösteren VS'nin ekran görüntüsü.

Şekil 6-7. Basit bir CRUD Web API mikro hizmetindeki bağımlılıklar

API projesi, tüm temel paketlere başvurular içeren Microsoft.AspNetCore.App NuGet paketine başvurular içerir. Başka paketler de içerebilir.

Entity Framework Core ile CRUD Web API hizmetlerini uygulama

Entity Framework (EF) Core, popüler Entity Framework veri erişim teknolojisinin basit, genişletilebilir ve platformlar arası bir sürümüdür. EF Core, .NET geliştiricilerinin .NET nesnelerini kullanarak bir veritabanıyla çalışmasını sağlayan nesne ilişkisel eşleyicidir (ORM).

Katalog mikro hizmeti, veritabanı Linux Docker için SQL Server görüntüsüne sahip bir kapsayıcıda çalıştığından EF ve SQL Server sağlayıcısını kullanır. Ancak veritabanı, Windows şirket içi veya Azure SQL DB gibi herhangi bir SQL Server'a dağıtılabilir. Değiştirmeniz gereken tek şey, ASP.NET Web API mikro hizmetindeki bağlantı dizesi.

Veri modeli

EF Core ile veri erişimi bir model kullanılarak gerçekleştirilir. Model, (etki alanı modeli) varlık sınıflarından ve veritabanıyla bir oturumu temsil eden ve verileri sorgulamanıza ve kaydetmenize olanak sağlayan türetilmiş bir bağlamdan (DbContext) oluşur. Mevcut bir veritabanından model oluşturabilir, modeli veritabanınızla eşleşecek şekilde el ile kodlayabilir veya modelinizden bir veritabanı oluşturmak için EF geçişleri tekniğini kullanarak kod öncelikli yaklaşımı kullanabilirsiniz (bu, modeliniz zaman içinde değiştikçe veritabanını geliştirmeyi kolaylaştırır). Katalog mikro hizmeti için son yaklaşım kullanılmıştır. Aşağıdaki kod örneğinde, basit bir Düz Eski Sınıf Nesnesi (POCO) varlık sınıfı olan CatalogItem varlık sınıfının bir örneğini görebilirsiniz.

public class CatalogItem
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public string PictureFileName { get; set; }
    public string PictureUri { get; set; }
    public int CatalogTypeId { get; set; }
    public CatalogType CatalogType { get; set; }
    public int CatalogBrandId { get; set; }
    public CatalogBrand CatalogBrand { get; set; }
    public int AvailableStock { get; set; }
    public int RestockThreshold { get; set; }
    public int MaxStockThreshold { get; set; }

    public bool OnReorder { get; set; }
    public CatalogItem() { }

    // Additional code ...
}

Veritabanıyla bir oturumu temsil eden bir DbContext de gereklidir. Katalog mikro hizmeti için CatalogContext sınıfı, aşağıdaki örnekte gösterildiği gibi DbContext temel sınıfından türetilir:

public class CatalogContext : DbContext
{
    public CatalogContext(DbContextOptions<CatalogContext> options) : base(options)
    { }
    public DbSet<CatalogItem> CatalogItems { get; set; }
    public DbSet<CatalogBrand> CatalogBrands { get; set; }
    public DbSet<CatalogType> CatalogTypes { get; set; }

    // Additional code ...
}

Ek DbContext uygulamalarınız olabilir. Örneğin, örnek Catalog.API mikro hizmette, veritabanına ilk kez erişmeye çalıştığında örnek verileri otomatik olarak doldurduğu adlı CatalogContextSeed ikinci bir DbContext ad vardır. Bu yöntem tanıtım verileri ve otomatik test senaryoları için de kullanışlıdır.

DbContextiçinde, nesnesini/veritabanı varlık eşlemelerini ve diğer EF genişletilebilirlik noktalarını özelleştirmek için yöntemini kullanırsınızOnModelCreating.

Web API denetleyicilerinden veri sorgulama

Varlık sınıflarınızın örnekleri genellikle aşağıdaki örnekte gösterildiği gibi DilLe Tümleşik Sorgu (LINQ) kullanılarak veritabanından alınır:

[Route("api/v1/[controller]")]
public class CatalogController : ControllerBase
{
    private readonly CatalogContext _catalogContext;
    private readonly CatalogSettings _settings;
    private readonly ICatalogIntegrationEventService _catalogIntegrationEventService;

    public CatalogController(
        CatalogContext context,
        IOptionsSnapshot<CatalogSettings> settings,
        ICatalogIntegrationEventService catalogIntegrationEventService)
    {
        _catalogContext = context ?? throw new ArgumentNullException(nameof(context));
        _catalogIntegrationEventService = catalogIntegrationEventService
            ?? throw new ArgumentNullException(nameof(catalogIntegrationEventService));

        _settings = settings.Value;
        context.ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
    }

    // GET api/v1/[controller]/items[?pageSize=3&pageIndex=10]
    [HttpGet]
    [Route("items")]
    [ProducesResponseType(typeof(PaginatedItemsViewModel<CatalogItem>), (int)HttpStatusCode.OK)]
    [ProducesResponseType(typeof(IEnumerable<CatalogItem>), (int)HttpStatusCode.OK)]
    [ProducesResponseType((int)HttpStatusCode.BadRequest)]
    public async Task<IActionResult> ItemsAsync(
        [FromQuery]int pageSize = 10,
        [FromQuery]int pageIndex = 0,
        string ids = null)
    {
        if (!string.IsNullOrEmpty(ids))
        {
            var items = await GetItemsByIdsAsync(ids);

            if (!items.Any())
            {
                return BadRequest("ids value invalid. Must be comma-separated list of numbers");
            }

            return Ok(items);
        }

        var totalItems = await _catalogContext.CatalogItems
            .LongCountAsync();

        var itemsOnPage = await _catalogContext.CatalogItems
            .OrderBy(c => c.Name)
            .Skip(pageSize * pageIndex)
            .Take(pageSize)
            .ToListAsync();

        itemsOnPage = ChangeUriPlaceholder(itemsOnPage);

        var model = new PaginatedItemsViewModel<CatalogItem>(
            pageIndex, pageSize, totalItems, itemsOnPage);

        return Ok(model);
    }
    //...
}
Verileri kaydetme

Veriler, varlık sınıflarınızın örnekleri kullanılarak veritabanında oluşturulur, silinir ve değiştirilir. Web API denetleyicilerinize aşağıdaki sabit kodlanmış örnek gibi kodlar (bu örnekte sahte veriler) ekleyebilirsiniz.

var catalogItem = new CatalogItem() {CatalogTypeId=2, CatalogBrandId=2,
                                     Name="Roslyn T-Shirt", Price = 12};
_context.Catalog.Add(catalogItem);
_context.SaveChanges();
ASP.NET Core ve Web API denetleyicilerine Bağımlılık Ekleme

ASP.NET Core'da, kutudan bağımlılık ekleme (DI) kullanabilirsiniz. Tercih ettiğiniz IoC kapsayıcısını isterseniz ASP.NET Core altyapısına takabilirsiniz ancak üçüncü taraf Bir Denetim Ters Çevirme (IoC) kapsayıcısı ayarlamanız gerekmez. Bu durumda, gerekli EF DBContext veya ek depoları denetleyici oluşturucu aracılığıyla doğrudan ekleyebileceğiniz anlamına gelir.

CatalogController Daha önce bahsedilen sınıfta, CatalogContext (öğesinden DbContextdevralan) türü, oluşturucudaki CatalogController() diğer gerekli nesnelerle birlikte eklenir.

Web API projesinde ayarlanması gereken önemli bir yapılandırma, hizmetin IoC kapsayıcısına DbContext sınıf kaydıdır. Bunu genellikle aşağıdaki basitleştirilmiş örnekte gösterildiği gibi yöntemini çağırarak builder.Services.AddDbContext<CatalogContext>() Program.cs dosyasında yaparsınız:

// Additional code...

builder.Services.AddDbContext<CatalogContext>(options =>
{
    options.UseSqlServer(builder.Configuration["ConnectionString"],
    sqlServerOptionsAction: sqlOptions =>
    {
        sqlOptions.MigrationsAssembly(
            typeof(Program).GetTypeInfo().Assembly.GetName().Name);

        //Configuring Connection Resiliency:
        sqlOptions.
            EnableRetryOnFailure(maxRetryCount: 5,
            maxRetryDelay: TimeSpan.FromSeconds(30),
            errorNumbersToAdd: null);
    });

    // Changing default behavior when client evaluation occurs to throw.
    // Default in EFCore would be to log warning when client evaluation is done.
    options.ConfigureWarnings(warnings => warnings.Throw(
        RelationalEventId.QueryClientEvaluationWarning));
});

Ek kaynaklar

Docker kapsayıcıları tarafından kullanılan DB bağlantı dizesi ve ortam değişkenleri

aşağıdaki örnekte gösterildiği gibi ASP.NET Core ayarlarını kullanabilir ve settings.json dosyanıza bir Bağlan ionString özelliği ekleyebilirsiniz:

{
    "ConnectionString": "Server=tcp:127.0.0.1,5433;Initial Catalog=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]",
    "ExternalCatalogBaseUrl": "http://host.docker.internal:5101",
    "Logging": {
        "IncludeScopes": false,
        "LogLevel": {
            "Default": "Debug",
            "System": "Information",
            "Microsoft": "Information"
        }
    }
}

settings.json dosyası, Bağlan ionString özelliği veya diğer herhangi bir özellik için varsayılan değerlere sahip olabilir. Ancak bu özellikler, Docker kullanılırken docker-compose.override.yml dosyasında belirttiğiniz ortam değişkenlerinin değerleri tarafından geçersiz kılınır.

docker-compose.yml veya docker-compose.override.yml dosyalarınızdan, Docker'ın bunları aşağıdaki docker-compose.override.yml dosyasında gösterildiği gibi işletim sistemi ortam değişkenleri olarak ayarlaması için bu ortam değişkenlerini başlatabilirsiniz (bağlantı dizesi ve diğer satırlar bu örnekte kaydırılır, ancak kendi dosyanızda kaydırılmaz).

# docker-compose.override.yml

#
catalog-api:
  environment:
    - ConnectionString=Server=sqldata;Database=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]
    # Additional environment variables for this service
  ports:
    - "5101:80"

Çözüm düzeyindeki docker-compose.yml dosyaları yalnızca proje veya mikro hizmet düzeyindeki yapılandırma dosyalarından daha esnek değildir, aynı zamanda Docker-compose dosyalarında bildirilen ortam değişkenlerini Azure DevOps Services Docker dağıtım görevleri gibi dağıtım araçlarınızdan ayarlanan değerlerle geçersiz kılarsanız daha güvenlidir.

Son olarak, önceki bir kod örneğinde gösterildiği gibi kullanarak builder.Configuration\["ConnectionString"\]kodunuzdan bu değeri alabilirsiniz.

Ancak üretim ortamları için bağlantı dizesi gibi gizli dizileri depolamanın ek yollarını keşfetmek isteyebilirsiniz. Uygulama gizli dizilerini yönetmenin mükemmel bir yolu Azure Key Vault kullanmaktır.

Azure Key Vault, bulut uygulamalarınız ve hizmetleriniz tarafından kullanılan şifreleme anahtarlarını ve gizli dizileri depolamaya ve korumaya yardımcı olur. Gizli dizi, API anahtarları, bağlantı dizesi' ler, parolalar vb. gibi sıkı denetimi korumak istediğiniz her şeydir ve sıkı denetim kullanım günlüğünü, süre sonunu ayarlamayı, erişimi yönetmeyi içerir.

Azure Key Vault, herkese bildirmeye gerek kalmadan uygulama gizli dizileri kullanımının ayrıntılı bir denetim düzeyine olanak tanır. Gizli diziler geliştirme veya işlemleri kesintiye uğratmadan gelişmiş güvenlik için bile döndürülebilir.

Uygulamaların Key Vault kullanabilmesi için kuruluşun Active Directory'sine kaydedilmesi gerekir.

Daha fazla ayrıntı için Key Vault Kavramları belgelerine bakabilirsiniz.

ASP.NET Web API'lerinde sürüm oluşturma uygulama

İş gereksinimleri değiştikçe yeni kaynak koleksiyonları eklenebilir, kaynaklar arasındaki ilişkiler değişebilir ve kaynaklardaki verilerin yapısı değiştirilebilir. Web API'sini yeni gereksinimleri işleyecek şekilde güncelleştirmek oldukça kolay bir işlemdir, ancak bu tür değişikliklerin Web API'sini kullanan istemci uygulamaları üzerindeki etkilerini göz önünde bulundurmanız gerekir. Bir Web API'sini tasarlayan ve uygulayan geliştirici bu API üzerinde tam denetime sahip olsa da, geliştirici uzaktan çalışan üçüncü taraf kuruluşlar tarafından oluşturulabilecek istemci uygulamaları üzerinde aynı düzeyde denetime sahip değildir.

Sürüm oluşturma, bir Web API'sinin kullanıma sağladığı özellikleri ve kaynakları belirtmesini sağlar. Daha sonra bir istemci uygulaması, bir özelliğin veya kaynağın belirli bir sürümüne istek gönderebilir. Sürüm oluşturma uygulamak için çeşitli yaklaşımlar vardır:

  • URI sürümü oluşturma

  • Sorgu dizesi sürümü oluşturma

  • Üst bilgi sürümü oluşturma

Sorgu dizesi ve URI sürüm oluşturma, uygulanması en kolay olanlardır. Üst bilgi sürümü oluşturma iyi bir yaklaşımdır. Ancak, üst bilgi sürümü oluşturma, URI sürümü oluşturma kadar açık ve basit değildir. URL sürümü oluşturma en basit ve en açık olduğundan, eShopOnContainers örnek uygulaması URI sürüm oluşturma kullanır.

URI sürüm oluşturma ile, eShopOnContainers örnek uygulamasında olduğu gibi, Web API'sini her değiştirdiğinizde veya kaynakların şemasını değiştirdiğinizde, her kaynağın URI'sine bir sürüm numarası eklersiniz. Mevcut URI'ler, istenen sürümle eşleşen şemaya uyan kaynakları döndürerek önceki gibi çalışmaya devam etmelidir.

Aşağıdaki kod örneğinde gösterildiği gibi, sürüm Web API denetleyicisindeki Route özniteliği kullanılarak ayarlanabilir ve bu da sürümü URI'de (bu örnekte v1) açık hale getirir.

[Route("api/v1/[controller]")]
public class CatalogController : ControllerBase
{
    // Implementation ...

Bu sürüm oluşturma mekanizması basittir ve isteği uygun uç noktaya yönlendiren sunucuya bağlıdır. Ancak, REST kullanırken daha gelişmiş bir sürüm oluşturma ve en iyi yöntem için hiper aracı kullanmalı ve HATEOAS (Uygulama Durumunun Altyapısı olarak Köprü Metni) uygulamalısınız.

Ek kaynaklar

ASP.NET Core Web API'nizden Swagger açıklama meta verileri oluşturma

Swagger, RESTful API'lerinizi tasarlamanıza, oluşturmanıza, belgelendirmenize ve kullanmanıza yardımcı olan büyük bir araç ekosistemi tarafından desteklenen yaygın olarak kullanılan bir açık kaynak çerçevesidir. API açıklama meta veri etki alanı için standart hale geliyor. Veri temelli mikro hizmetler veya daha gelişmiş etki alanı temelli mikro hizmetler (aşağıdaki bölümde açıklandığı gibi) gibi her tür mikro hizmete Swagger açıklama meta verileri eklemeniz gerekir.

Swagger'ın kalbi, JSON veya YAML dosyasındaki API açıklama meta verileri olan Swagger belirtimidir. Belirtim, API'niz için RESTful sözleşmesini oluşturur ve kolay geliştirme, bulma ve tümleştirme için tüm kaynaklarını ve işlemlerini hem insan hem de makine tarafından okunabilir bir biçimde ayrıntılarıyla açıklar.

Belirtim, OpenAPI Belirtiminin (OAS) temelini oluşturur ve RESTful arabirimlerinin tanımlanma şeklini standartlaştırmak için açık, şeffaf ve işbirliğine dayalı bir toplulukta geliştirilmiştir.

Belirtim, bir hizmetin nasıl bulunabileceğine ve özelliklerinin nasıl anlaşılacağına ilişkin yapıyı tanımlar. Bir web düzenleyicisi ve Spotify, Uber, Slack ve Microsoft gibi şirketlerin Swagger belirtimlerine örnekler de dahil olmak üzere daha fazla bilgi için Swagger sitesine () bakınhttps://swagger.io.

Swagger neden kullanılır?

API'leriniz için Swagger meta verileri oluşturmanın başlıca nedenleri şunlardır.

Diğer ürünlerin API'lerinizi otomatik olarak kullanma ve tümleştirme olanağı. Onlarca ürün ve ticari araç ile birçok kitaplık ve çerçeve Swagger'ı destekler. Microsoft, Swagger tabanlı API'leri otomatik olarak kullanabilen aşağıdakiler gibi üst düzey ürünlere ve araçlara sahiptir:

API belgelerini otomatik olarak oluşturabilme. Karmaşık mikro hizmet tabanlı uygulamalar gibi büyük ölçekli RESTful API'leri oluşturduğunuzda, istek ve yanıt yüklerinde kullanılan farklı veri modellerine sahip birçok uç noktayı işlemeniz gerekir. Swagger ile birlikte doğru belgelere sahip olmak ve sağlam bir API gezginine sahip olmak, API'nizin başarılı olması ve geliştiriciler tarafından benimsenmesi için önemlidir.

Microsoft Flow, PowerApps ve Azure Logic Apps, API'lerin nasıl kullanılacağını ve bunlara nasıl bağlanacağınızı anlamak için Swagger'ın meta verilerini kullanır.

ASP.NET Core REST API uygulamaları için Swagger meta veri oluşturma işlemini, swagger-ui temelinde işlevsel API yardım sayfaları biçiminde otomatikleştirmeye yönelik çeşitli seçenekler vardır.

Muhtemelen en iyi bilinen şey şu anda eShopOnContainers'da kullanılan Swashbuckle'dır ve bu kılavuzda bazı ayrıntıları ele alacağız, ancak ayrıca bir Swagger veya OpenAPI belirtiminden ve hatta denetleyicileri içeren .dll tarayarak Typescript ve C# API istemcileri ve C# denetleyicileri oluşturabilen NSwag kullanma seçeneği de vardır. NSwagStudio kullanarak.

Swashbuckle NuGet paketiyle API Swagger meta veri oluşturmayı otomatikleştirme

Swagger meta verilerini el ile (JSON veya YAML dosyasında) oluşturmak yorucu olabilir. Ancak, dinamik olarak Swagger API meta verileri oluşturmak için Swashbuckle NuGet paketini kullanarak ASP.NET Web API hizmetlerinin API bulmasını otomatikleştirebilirsiniz.

Swashbuckle, ASP.NET Web API projeleriniz için otomatik olarak Swagger meta verileri oluşturur. ASP.NET Core Web API projelerini, geleneksel ASP.NET Web API'sini ve ASP.NET tabanlı Azure API Uygulaması, Azure Mobil Uygulama, Azure Service Fabric mikro hizmetleri gibi diğer özellikleri destekler. Ayrıca, başvuru uygulamasında olduğu gibi kapsayıcılara dağıtılan düz Web API'sini de destekler.

Swashbuckle, API tüketicileriniz için zengin bir keşif ve belge deneyimi sağlamak için API Gezgini ve Swagger veya swagger-ui'yi birleştirir. Swagger meta veri oluşturucu altyapısına ek olarak, Swashbuckle ayrıca Swashbuckle yüklendikten sonra otomatik olarak hizmet verecek ekli bir swagger-ui sürümü içerir.

Bu, geliştiricilerin API'nizi kullanmasına yardımcı olmak için API'nizi güzel bir bulma kullanıcı arabirimiyle tamamlayabileceğiniz anlamına gelir. Otomatik olarak oluşturulduğundan, API'nizi oluşturmaya odaklanmanıza olanak sağladığından az miktarda kod ve bakım gerektirir. API Gezgini'nin sonucu Şekil 6-8'e benzer.

eShopOContainers API'sini görüntüleyen Swagger API Gezgini'nin ekran görüntüsü.

Şekil 6-8. Swagger meta verilerini temel alan Swashbuckle API Gezgini-eShopOnContainers katalog mikro hizmeti

Swashbuckle tarafından oluşturulan Swagger UI API belgeleri, yayımlanan tüm eylemleri içerir. API gezgini buradaki en önemli şey değildir. Swagger meta verilerinde kendisini tanımlayabilen bir Web API'niz olduğunda, API'niz birçok platformu hedefleyebilecek istemci proxy sınıfı kod oluşturucuları da dahil olmak üzere Swagger tabanlı araçlardan sorunsuz bir şekilde kullanılabilir. Örneğin, belirtildiği gibi AutoRest otomatik olarak .NET istemci sınıfları oluşturur. Ancak swagger-codegen gibi api istemci kitaplıklarının, sunucu saptamalarının ve belgelerin otomatik olarak kod oluşturulmasına olanak tanıyan ek araçlar da mevcuttur.

Şu anda Swashbuckle, ASP.NET Core uygulamaları için üst düzey metapackage Swashbuckle.AspNetCore altında beş iç NuGet paketinden oluşmaktadır.

Bu NuGet paketlerini Web API projenize yükledikten sonra, aşağıdaki basitleştirilmiş kodda olduğu gibi Program.cs sınıfında Swagger'ı yapılandırmanız gerekir:

// Add framework services.

builder.Services.AddSwaggerGen(options =>
{
    options.DescribeAllEnumsAsStrings();
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "eShopOnContainers - Catalog HTTP API",
        Version = "v1",
        Description = "The Catalog Microservice HTTP API. This is a Data-Driven/CRUD microservice sample"
    });
});

// Other startup code...

app.UseSwagger();

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

Bu işlem tamamlandıktan sonra uygulamanızı başlatabilir ve aşağıdaki gibi URL'leri kullanarak aşağıdaki Swagger JSON ve UI uç noktalarına göz atabilirsiniz:

  http://<your-root-url>/swagger/v1/swagger.json

  http://<your-root-url>/swagger/

Daha önce gibi http://<your-root-url>/swaggerbir URL için Swashbuckle tarafından oluşturulan kullanıcı arabirimini gördünüz. Şekil 6-9'da, herhangi bir API yöntemini nasıl test ettiğinizi de görebilirsiniz.

Kullanılabilir test araçlarını gösteren Swagger kullanıcı arabiriminin ekran görüntüsü.

Şekil 6-9. Katalog/Öğeler API'sinin yöntemini test eden Swashbuckle kullanıcı arabirimi

Swagger UI API'sinin ayrıntıları yanıtın bir örneğini gösterir ve geliştirici bulma için harika olan gerçek API'yi yürütmek için kullanılabilir. eShopOnContainers mikro hizmetinden oluşturulan Swagger JSON meta verilerini görmek için (araçların altında bu kullanılır), Visual Studio Code: REST İstemci uzantısını kullanarak bir istekte http://<your-root-url>/swagger/v1/swagger.json bulunabilirsiniz.

Ek kaynaklar

Geriİleri