Bagikan melalui

Membuat layanan mikro CRUD berbasis data sederhana

Petunjuk / Saran

Konten ini adalah kutipan dari eBook, .NET Microservices Architecture for Containerized .NET Applications, tersedia di .NET Docs atau sebagai PDF yang dapat diunduh gratis dan dapat dibaca secara offline.

Unduh PDF

Arsitektur Layanan Mikro .NET untuk thumbnail sampul eBook Aplikasi .NET Dalam Kontainer.

Bagian ini menguraikan cara membuat layanan mikro sederhana yang melakukan operasi buat, baca, perbarui, dan hapus (CRUD) pada sumber data.

Merancang layanan mikro CRUD sederhana

Dari sudut pandang desain, jenis layanan mikro kontainer ini sangat sederhana. Mungkin masalah yang harus diselesaikan sederhana, atau mungkin implementasinya hanyalah bukti konsep.

Diagram memperlihatkan pola desain internal layanan mikro CRUD sederhana.

Gambar 6-4. Desain internal untuk layanan mikro CRUD sederhana

Contoh layanan drive data sederhana semacam ini adalah layanan mikro katalog dari aplikasi sampel eShopOnContainers. Jenis layanan ini mengimplementasikan semua fungsinya dalam satu proyek Web API ASP.NET Core yang mencakup kelas untuk model datanya, logika bisnisnya, dan kode akses datanya. Ini juga menyimpan data terkait dalam database yang berjalan di SQL Server (sebagai kontainer lain untuk tujuan pengembangan/pengujian), tetapi juga bisa menjadi host SQL Server reguler, seperti yang ditunjukkan pada Gambar 6-5.

Diagram memperlihatkan kontainer layanan mikro berbasis data/CRUD.

Gambar 6-5. Desain layanan mikro berbasis data/CRUD sederhana

Diagram sebelumnya menunjukkan layanan mikro Katalog logis, yang menyertakan database Katalognya, yang dapat berada di host Docker yang sama atau tidak. Memiliki database di host Docker yang sama mungkin baik untuk pengembangan, tetapi tidak untuk produksi. Saat mengembangkan layanan semacam ini, Anda hanya perlu ASP.NET Core dan API akses data atau ORM seperti Inti Entity Framework. Anda juga dapat menghasilkan metadata Swagger secara otomatis melalui Swashbuckle untuk memberikan deskripsi tentang apa yang ditawarkan layanan Anda, seperti yang dijelaskan di bagian berikutnya.

Perhatikan bahwa menjalankan server database seperti SQL Server dalam kontainer Docker sangat bagus untuk lingkungan pengembangan, karena Anda dapat mengaktifkan dan menjalankan semua dependensi tanpa perlu menyediakan database di cloud atau lokal. Pendekatan ini mudah untuk menjalankan pengujian integrasi. Namun, untuk lingkungan produksi, menjalankan server database dalam kontainer tidak disarankan, karena Anda biasanya tidak mendapatkan ketersediaan tinggi dengan pendekatan tersebut. Untuk lingkungan produksi di Azure, disarankan agar Anda menggunakan Azure SQL DB atau teknologi database lainnya yang dapat memberikan high availability dan skalabilitas tinggi. Misalnya, untuk pendekatan NoSQL, Anda dapat memilih CosmosDB.

Terakhir, dengan mengedit file metadata Dockerfile dan docker-compose.yml, Anda dapat mengonfigurasi cara gambar kontainer ini akan dibuat—gambar dasar apa yang akan digunakannya, ditambah pengaturan desain seperti nama internal dan eksternal dan port TCP.

Menerapkan layanan mikro CRUD sederhana dengan ASP.NET Core

Untuk menerapkan layanan mikro CRUD sederhana menggunakan .NET dan Visual Studio, Anda mulai dengan membuat proyek Web API ASP.NET Core sederhana (berjalan di .NET sehingga dapat berjalan pada host Linux Docker), seperti yang ditunjukkan pada Gambar 6-6.

Cuplikan layar Visual Studios yang memperlihatkan pengaturan proyek.

Gambar 6-6. Membuat proyek Web API ASP.NET Core di Visual Studio 2019

Untuk membuat Proyek Web API ASP.NET Core, pertama pilih Aplikasi Web ASP.NET Core lalu pilih jenis API. Setelah membuat proyek, Anda dapat mengimplementasikan pengontrol MVC seperti yang Anda lakukan di proyek API Web lainnya, menggunakan Entity Framework API atau API lainnya. Dalam proyek Web API baru, Anda dapat melihat bahwa satu-satunya dependensi yang Anda miliki di layanan mikro tersebut ada di ASP.NET Core itu sendiri. Secara internal, dalam dependensi Microsoft.AspNetCore.All, ia mereferensikan Entity Framework dan banyak paket NuGet .NET lainnya, seperti yang ditunjukkan pada Gambar 6-7.

Cuplikan layar VS memperlihatkan dependensi NuGet dari Catalog.Api.

Gambar 6-7. Dependensi dalam layanan mikro CRUD Web API sederhana

Proyek API mencakup referensi ke paket NuGet Microsoft.AspNetCore.App, yang mencakup referensi ke semua paket penting. Ini juga dapat mencakup beberapa paket lain.

Menerapkan layanan CRUD Web API dengan Entity Framework Core

Entity Framework (EF) Core adalah versi ringan, dapat diperluas, dan lintas platform dari teknologi akses data Entity Framework yang populer. EF Core adalah pemeta relasional objek (ORM) yang memungkinkan pengembang .NET bekerja dengan database menggunakan objek .NET.

Layanan mikro katalog menggunakan EF dan penyedia SQL Server karena databasenya berjalan dalam kontainer dengan SQL Server untuk gambar Linux Docker. Namun, database dapat disebarkan ke dalam SQL Server apa pun, seperti Windows lokal atau Azure SQL DB. Satu-satunya hal yang perlu Anda ubah adalah string koneksi di layanan mikro Web API ASP.NET.

Model data

Dengan EF Core, akses data dilakukan dengan menggunakan model. Model terdiri dari kelas entitas (model domain) dan konteks turunan (DbContext) yang mewakili sesi dengan database, memungkinkan Anda mengkueri dan menyimpan data. Anda dapat membuat model dari database yang sudah ada, membuat kode model secara manual agar sesuai dengan database, atau menggunakan teknik migrasi EF untuk membuat database dari model, menggunakan pendekatan code-first (yang memudahkan untuk mengembangkan database saat model berubah dari waktu ke waktu). Untuk layanan mikro katalog, pendekatan terakhir telah digunakan. Anda dapat melihat contoh kelas entitas CatalogItem dalam contoh kode berikut, yang merupakan kelas entitas Plain Old Class Object (POCO) sederhana.

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 ...
}

Anda juga memerlukan DbContext yang mewakili sesi dengan database. Untuk layanan mikro katalog, kelas CatalogContext berasal dari kelas dasar DbContext, seperti yang ditunjukkan dalam contoh berikut:

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 ...
}

Anda dapat memiliki implementasi DbContext tambahan. Misalnya, dalam sampel layanan mikro Catalog.API, ada DbContext kedua bernama CatalogContextSeed saat ia secara otomatis mengisi data sampel saat pertama kali mencoba mengakses database. Metode ini berguna untuk data demo dan juga untuk skenario pengujian otomatis.

Dalam DbContext, Anda menggunakan metode OnModelCreating untuk menyesuaikan pemetaan entitas objek/database dan titik ekstensibilitas EF lainnya.

Mengkueri data dari pengontrol API Web

Instans kelas entitas biasanya diambil dari database menggunakan Language-Integrated Query (LINQ), seperti yang ditunjukkan dalam contoh berikut:

[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);
    }
    //...
}
Menyimpan data

Data dibuat, dihapus, dan dimodifikasi dalam database menggunakan instans kelas entitas Anda. Anda dapat menambahkan kode seperti contoh yang dikodekan secara permanen berikut (dalam hal ini, data tiruan) ke pengontrol API Web.

var catalogItem = new CatalogItem() {CatalogTypeId=2, CatalogBrandId=2,
                                     Name="Roslyn T-Shirt", Price = 12};
_context.Catalog.Add(catalogItem);
_context.SaveChanges();
Injeksi Dependensi di ASP.NET Core dan pengontrol Web API

Di ASP.NET Core, Anda dapat menggunakan Injeksi Dependensi (DI) di luar kotak. Anda tidak perlu menyiapkan kontainer Inversion of Control (IoC) pihak ketiga, meskipun Anda dapat menyambungkan kontainer IoC pilihan Anda ke infrastruktur ASP.NET Core jika ingin. Dalam hal ini, itu berarti Anda dapat langsung menginjeksi EF DBContext yang diperlukan atau repositori tambahan melalui konstruktor pengontrol.

Di kelas CatalogController yang disebutkan sebelumnya, jenis CatalogContext (yang diwariskan dari DbContext) diinjeksikan bersama dengan objek lain yang diperlukan dalam konstruktor CatalogController().

Konfigurasi penting untuk disiapkan dalam proyek API Web adalah pendaftaran kelas DbContext ke dalam kontainer IoC layanan. Anda biasanya melakukannya dalam file Program.cs dengan memanggil metode , seperti yang builder.Services.AddDbContext<CatalogContext>() ditunjukkan dalam contoh yang disederhanakan berikut:

// 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));
});

Penting

Microsoft menyarankan agar Anda menggunakan alur autentikasi paling aman yang tersedia. Jika Anda menyambungkan ke Azure SQL, Identitas Terkelola untuk sumber daya Azure adalah metode autentikasi yang direkomendasikan.

Sumber Daya Tambahan:

String koneksi DB dan variabel lingkungan yang digunakan oleh kontainer Docker

Anda dapat menggunakan pengaturan ASP.NET Core dan menambahkan properti ConnectionString ke file settings.json Seperti yang ditunjukkan dalam contoh berikut:

{
    "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"
        }
    }
}

File settings.json dapat memiliki nilai default untuk properti ConnectionString atau untuk properti lainnya. Namun, properti tersebut akan ditimpa oleh nilai variabel lingkungan yang Anda tentukan dalam file docker-compose.override.yml, saat menggunakan Docker.

Dari file docker-compose.yml atau docker-compose.override.yml, Anda dapat menginisialisasi variabel lingkungan tersebut sehingga Docker akan mengaturnya sebagai variabel lingkungan OS untuk Anda, seperti yang ditunjukkan dalam file docker-compose.override.yml berikut (string koneksi dan baris lain yang dibungkus dalam contoh ini, tetapi tidak akan terbungkus dalam file Anda sendiri).

# 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"

Penting

Microsoft menyarankan agar Anda menggunakan alur autentikasi paling aman yang tersedia. Jika Anda menyambungkan ke Azure SQL, Identitas Terkelola untuk sumber daya Azure adalah metode autentikasi yang direkomendasikan.

File docker-compose.yml di tingkat solusi tidak hanya lebih fleksibel daripada file konfigurasi di tingkat proyek atau layanan mikro, tetapi juga lebih aman jika Anda mengganti variabel lingkungan yang dideklarasikan pada file docker-compose dengan nilai yang diatur dari alat penyebaran, seperti dari tugas penyebaran Docker Layanan Azure DevOps.

Terakhir, Anda bisa mendapatkan nilai tersebut dari kode Anda dengan menggunakan builder.Configuration["ConnectionString"], seperti yang ditunjukkan dalam contoh kode sebelumnya.

Namun, untuk lingkungan produksi, Anda mungkin ingin menjelajahi cara lain terkait menyimpan rahasia seperti string koneksi. Cara terbaik untuk mengelola rahasia aplikasi adalah menggunakan Azure Key Vault.

Azure Key Vault membantu melindungi kunci kriptografi dan rahasia yang digunakan oleh aplikasi dan layanan cloud. Rahasia adalah apa pun yang ingin Anda kontrol secara ketat, seperti kunci API, string koneksi, kata sandi, dll. dan kontrol ketat termasuk antara lain pengelogan penggunaan, pengaturan kedaluwarsa, dan mengelola akses.

Azure Key Vault memungkinkan tingkat kontrol terperinci dari penggunaan rahasia aplikasi tanpa perlu memberi tahu siapa pun. Rahasia bahkan dapat diputar untuk keamanan yang ditingkatkan tanpa mengganggu pengembangan atau operasi.

Aplikasi harus terdaftar di Active Directory organisasi, sehingga mereka dapat menggunakan Key Vault.

Anda dapat memeriksa dokumentasi Konsep Key Vault untuk detail selengkapnya.

Menerapkan penerapan versi di API Web ASP.NET

Saat persyaratan bisnis berubah, kumpulan sumber daya baru dapat ditambahkan, hubungan antara sumber daya dapat berubah, dan struktur data dalam sumber daya dapat diubah. Meskipun memperbarui API web untuk menangani persyaratan baru atau yang berbeda adalah proses yang relatif mudah, Anda harus mempertimbangkan efek perubahan tersebut pada aplikasi klien yang menggunakan API web. Masalahnya adalah meskipun pengembang yang merancang dan menerapkan API web memiliki kontrol penuh atas API tersebut, pengembang tidak memiliki tingkat kontrol yang sama atas aplikasi klien, yang mungkin dibangun oleh organisasi pihak ketiga yang beroperasi dari jarak jauh.

Penerapan versi memungkinkan API Web menunjukkan fitur dan sumber daya yang dieksposnya. Aplikasi klien kemudian dapat mengirimkan permintaan ke versi tertentu dari fitur atau sumber daya. Ada beberapa pendekatan untuk menerapkan penerapan versi:

  • Penerapan versi URI
  • Penerapan versi string kueri
  • Penerapan versi header

String kueri dan penerapan versi URI adalah yang paling sederhana untuk diimplementasikan. Penerapan versi header adalah pendekatan yang baik. Namun, penerapan versi header tidak eksplisit dan semudah seperti penerapan versi URI. Karena penerapan versi URL adalah yang paling sederhana dan paling eksplisit, aplikasi sampel eShopOnContainers menggunakan penerapan versi URI.

Dengan penerapan versi URI, seperti dalam aplikasi sampel eShopOnContainers, setiap kali Anda memodifikasi API Web atau mengubah skema sumber daya, Anda menambahkan nomor versi ke URI untuk setiap sumber daya. URI yang ada harus terus beroperasi seperti sebelumnya, mengembalikan sumber daya yang sesuai dengan skema yang cocok dengan versi yang diminta.

Seperti yang ditunjukkan dalam contoh kode berikut, versi dapat diatur dengan menggunakan atribut Rute di pengontrol Web API, yang membuat versi eksplisit dalam URI (dalam hal ini, v1).

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

Mekanisme penerapan versi ini sangat sederhana tetapi bergantung pada server yang merutekan permintaan ke titik akhir yang sesuai. Namun, untuk penerapan versi yang lebih canggih dan metode terbaik saat menggunakan REST, Anda harus menggunakan hypermedia dan mengimplementasikan HATEOAS (Hypertext sebagai Engine of Application State).

Sumber Daya Tambahan:

Menghasilkan metadata deskripsi Swagger dari Web API ASP.NET Core Anda

Swagger adalah kerangka kerja sumber terbuka yang umum digunakan yang didukung oleh ekosistem alat besar yang membantu Anda merancang, membangun, mendokumentasikan, dan menggunakan API RESTful. Ini menjadi standar untuk domain metadata deskripsi API. Anda harus menyertakan metadata deskripsi Swagger dengan segala jenis layanan mikro, baik layanan mikro berbasis data atau layanan mikro berbasis domain yang lebih canggih (seperti yang dijelaskan di bagian berikut).

Inti dari Swagger adalah spesifikasi Swagger, yaitu metadata deskripsi API dalam file JSON atau YAML. Spesifikasi ini membuat kontrak RESTful untuk API Anda, merinci semua sumber daya dan operasinya dalam format yang dapat dibaca manusia dan mesin untuk pengembangan, penemuan, dan integrasi yang mudah.

Spesifikasi ini adalah dasar dari Spesifikasi OpenAPI (OAS) dan dikembangkan dalam komunitas yang terbuka, transparan, dan kolaboratif untuk menstandarkan cara penentuan antarmuka RESTful.

Spesifikasi ini mendefinisikan struktur tentang cara layanan dapat ditemukan dan bagaimana kemampuannya dipahami. Untuk informasi selengkapnya, termasuk editor web dan contoh spesifikasi Swagger dari perusahaan seperti Spotify, Uber, Slack, dan Microsoft, lihat situs Swagger (https://swagger.io).

Mengapa menggunakan Swagger?

Alasan utama untuk menghasilkan metadata Swagger untuk API Anda adalah sebagai berikut.

Kemampuan produk lain untuk mengonsumsi dan mengintegrasikan API secara otomatis. Puluhan produk dan alat komersial serta banyak pustaka dan kerangka kerja mendukung Swagger. Microsoft memiliki produk dan alat tingkat tinggi yang dapat secara otomatis menggunakan API berbasis Swagger, seperti berikut ini:

Kemampuan untuk menghasilkan dokumentasi API secara otomatis. Saat Anda membuat API RESTful skala besar, seperti aplikasi berbasis layanan mikro yang kompleks, Anda perlu menangani banyak titik akhir dengan model data berbeda yang digunakan dalam payload permintaan dan respons. Memiliki dokumentasi yang tepat dan memiliki penjelajah API yang kuat, seperti yang Anda dapatkan dengan Swagger, adalah kunci untuk keberhasilan API dan adopsi oleh pengembang.

Metadata Swagger adalah yang digunakan oleh Alur Microsoft, PowerApps, dan Azure Logic Apps untuk memahami cara menggunakan API dan menyambungkannya.

Ada beberapa opsi untuk mengotomatiskan pembuatan metadata Swagger untuk aplikasi ASP.NET Core REST API, dalam bentuk halaman bantuan API fungsional, berdasarkan swagger-ui.

Mungkin yang paling diketahui adalah Swashbuckle, yang saat ini digunakan dalam eShopOnContainers dan kita akan membahas beberapa detail dalam panduan ini tetapi ada juga opsi untuk menggunakan NSwag, yang dapat menghasilkan klien Typescript dan C# API, serta pengontrol C#, dari spesifikasi Swagger atau OpenAPI dan bahkan dengan memindai .dll yang berisi pengontrol, menggunakan NSwagStudio.

Cara mengotomatiskan pembuatan metadata API Swagger dengan paket Swashbuckle NuGet

Menghasilkan metadata Swagger secara manual (dalam file JSON atau YAML) dapat menjadi pekerjaan yang melelahkan. Namun, Anda dapat mengotomatiskan penemuan layanan Web API ASP.NET dengan menggunakan paket NuGet Swashbuckle untuk menghasilkan metadata API Swagger secara dinamis.

Swashbuckle secara otomatis menghasilkan metadata Swagger untuk proyek Web API ASP.NET. Ini mendukung proyek Web API ASP.NET Core dan Web API ASP.NET tradisional dan lainnya, seperti layanan mikro Azure Service Fabric, Azure API App, Azure Mobile App, berdasarkan ASP.NET. Ini juga mendukung Web API biasa yang disebarkan pada kontainer, seperti untuk aplikasi referensi.

Swashbuckle menggabungkan API Explorer dan Swagger atau swagger-ui untuk memberikan pengalaman penemuan dan dokumentasi yang kaya bagi konsumen API Anda. Selain mesin generator metadata Swagger-nya, Swashbuckle juga berisi versi swagger-ui yang disematkan, yang akan secara otomatis berfungsi setelah Swashbuckle dipasang.

Ini berarti Anda dapat melengkapi API dengan UI penemuan yang bagus untuk membantu pengembang menggunakan API Anda. Ini membutuhkan sejumlah kecil kode dan pemeliharaan karena dibuat secara otomatis, memungkinkan Anda berfokus pada membangun API. Hasil untuk API Explorer terlihat seperti Gambar 6-8.

Cuplikan layar Swagger API Explorer menampilkan eShopOContainers API.

Gambar 6-8. Swashbuckle API Explorer berdasarkan metadata Swagger—layanan mikro katalog eShopOnContainers

Dokumentasi API UI Swashbuckle yang dihasilkan Swagger mencakup semua tindakan yang diterbitkan. Penjelajah API bukanlah hal yang paling penting di sini. Setelah Anda memiliki API Web yang dapat menggambarkan dirinya sendiri dalam metadata Swagger, API dapat digunakan dengan mulus dari alat berbasis Swagger, termasuk generator kode kelas proksi klien yang dapat menargetkan banyak platform. Misalnya, seperti yang disebutkan, AutoRest secara otomatis menghasilkan kelas klien .NET. Tetapi alat tambahan seperti swagger-codegen juga tersedia, yang memungkinkan pembuatan kode pustaka klien API, stub server, dan dokumentasi secara otomatis.

Saat ini, Swashbuckle terdiri dari lima paket NuGet internal di bawah paket meta Swashbuckle.AspNetCore tingkat tinggi untuk aplikasi ASP.NET Core.

Setelah menginstal paket NuGet ini di proyek API Web, Anda perlu mengonfigurasi Swagger di kelas Program.cs, seperti dalam kode yang disederhanakan berikut:

// 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");
    });
}

Setelah ini selesai, Anda dapat memulai aplikasi dan menelusuri titik akhir JSON dan UI Swagger berikut menggunakan URL seperti ini:

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

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

Sebelumnya, Anda melihat UI yang dihasilkan yang dibuat oleh Swashbuckle untuk URL seperti http://<your-root-url>/swagger. Pada Gambar 6-9, Anda juga dapat melihat bagaimana Anda dapat menguji semua metode API.

Cuplikan layar antarmuka pengguna Swagger memperlihatkan alat pengujian yang tersedia.

Gambar 6-9. Antarmuka pengguna Swashbuckle menguji metode API Katalog/Item

Detail API antarmuka pengguna Swagger menunjukkan sampel respons dan dapat digunakan untuk menjalankan API nyata, yang sangat bagus untuk penemuan pengembang. Untuk melihat metadata Swagger JSON yang dihasilkan dari layanan mikro eShopOnContainers (yang merupakan apa yang digunakan alat di bawahnya), buat permintaan http://<your-root-url>/swagger/v1/swagger.json Anda menggunakan ekstensi Visual Studio Code: REST Client.

Sumber Daya Tambahan:

SebelumnyaBerikutnya