Cara menggunakan Swagger di ASP.Net Core

Anda akan sering ingin membuat dokumentasi untuk API Anda. Untuk membuat dokumentasi ini, Anda dapat memanfaatkan Swagger - alat yang dapat digunakan untuk memberikan representasi UI API Anda dengan mudah. Setelah Anda membuat dokumentasi Swagger untuk API Anda, Anda dapat melihat tanda tangan metode API Anda dan bahkan menguji metode API Anda juga.

Swashbuckle adalah proyek open source untuk menghasilkan dokumen Swagger. Artikel ini menyajikan diskusi tentang bagaimana kita dapat memanfaatkan Swashbuckle untuk menghasilkan dokumentasi interaktif untuk RESTful API kita.

Buat proyek ASP.Net Core

Pertama, mari buat proyek Inti ASP.Net di Visual Studio. Dengan asumsi Visual Studio 2017 atau Visual Studio 2019 diinstal di sistem Anda, ikuti langkah-langkah yang diuraikan di bawah ini untuk membuat proyek ASP.Net Core baru di Visual Studio.

  1. Luncurkan Visual Studio IDE.
  2. Klik "Buat proyek baru".
  3. Di jendela "Buat proyek baru", pilih "Aplikasi Web Inti ASP.Net" dari daftar templat yang ditampilkan.
  4. Klik Next. 
  5. Di jendela "Configure your new project" yang ditampilkan berikutnya, tentukan nama dan lokasi untuk proyek baru tersebut.
  6. Klik Buat. 
  7. Di jendela "Buat Aplikasi Web ASP.Net Core Baru", pilih .Net Core sebagai runtime dan ASP.Net Core 2.2 (atau yang lebih baru) dari daftar drop-down di bagian atas.
  8. Pilih "API" sebagai template proyek untuk membuat proyek ASP.Net Core Web API baru. 
  9. Pastikan kotak centang "Aktifkan Dukungan Docker" dan "Konfigurasi untuk HTTPS" tidak dicentang karena kami tidak akan menggunakan fitur tersebut di sini.
  10. Pastikan Autentikasi disetel sebagai "Tanpa Autentikasi" karena kami juga tidak akan menggunakan autentikasi.
  11. Klik Buat.

Mengikuti langkah-langkah ini akan membuat proyek ASP.Net Core baru di Visual Studio. Kami akan menggunakan proyek ini di bagian selanjutnya dari artikel ini untuk memeriksa bagaimana kami dapat membuat dokumentasi Swagger untuk ValuesController.

Instal middleware Swagger di ASP.Net Core

Jika Anda telah berhasil membuat proyek Inti ASP.Net, hal berikutnya yang harus Anda lakukan adalah menambahkan paket NuGet yang diperlukan ke proyek Anda. Untuk melakukan ini, pilih proyek di jendela Solution Explorer, klik kanan dan pilih "Kelola Paket NuGet ...." Di jendela Manajer Paket NuGet, cari paket Swashbuckle.AspNetCore dan instal. Alternatifnya, Anda dapat menginstal paket melalui NuGet Package Manager Console seperti yang ditunjukkan di bawah ini.

PM> Instal-Paket Swashbuckle.AspNetCore

Paket Swashbuckle.AspNetCore berisi alat yang diperlukan untuk menghasilkan dokumen API untuk ASP.Net Core.

Konfigurasikan middleware Swagger di ASP.Net Core

Untuk mengkonfigurasi Swagger, tulis kode berikut di metode ConfigureServices. Perhatikan bagaimana metode ekstensi AddSwaggerGen digunakan untuk menentukan metadata untuk dokumen API.

services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", Info baru

                {

                    Versi = "v1",

                    Judul = "Demo Kesombongan",

                    Description = "Demo Kesombongan untuk ValuesController",

                    TermsOfService = "Tidak Ada",

                    Kontak = Kontak baru () {Nama = "Joydip Kanjilal",

                    Email = "[email protected]",

                    Url = "www.google.com"}

                });

            });

Anda juga harus mengaktifkan UI Swagger dalam metode Configure seperti yang ditunjukkan di bawah ini.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

   c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

});

Berikut adalah kode lengkap dari kelas Startup untuk referensi Anda.

menggunakan Microsoft.AspNetCore.Builder;

menggunakan Microsoft.AspNetCore.Hosting;

menggunakan Microsoft.AspNetCore.Mvc;

menggunakan Microsoft.Extensions.Configuration;

menggunakan Microsoft.Extensions.DependencyInjection;

menggunakan Swashbuckle.AspNetCore.Swagger;

namespace SwaggerDemo

{

    kelas publik Startup

    {

        Startup publik (konfigurasi IConfiguration)

        {

            Konfigurasi = konfigurasi;

        }

        Konfigurasi IConfiguration publik {get; }

        public void ConfigureServices (layanan IServiceCollection)

        {

            services.AddMvc (). SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", Info baru

                {

                    Versi = "v1",

                    Judul = "Demo Kesombongan",

                    Description = "Demo Kesombongan untuk ValuesController",

                    TermsOfService = "Tidak Ada",

                    Kontak = Kontak baru () {Nama = "Joydip Kanjilal",

                    Email = "[email protected]",

                    Url = "www.google.com"

                }

                });

            });

        }

        Konfigurasi public void (aplikasi IApplicationBuilder,

       IHostingEnvironment env)

        {

            if (env.IsDevelopment ())

            {

                app.UseDeveloperExceptionPage ();

            }

            app.UseMvc ();

            app.UseSwagger ();

            app.UseSwaggerUI (c =>

            {

                c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

            });

        }

    }

}

Ini semua yang perlu Anda lakukan untuk memulai Swagger.

Jelajahi UI Swagger dari aplikasi ASP.Net Core Anda

Sekarang kami siap untuk menjalankan aplikasi dan menelusuri titik akhir Swagger. UI Swagger akan muncul seperti pada Gambar 1 di bawah ini. Perhatikan bagaimana Swagger menggunakan warna berbeda untuk verba HTTP GET, PUT, POST, dan DELETE. Anda dapat menjalankan setiap titik akhir yang ditunjukkan pada Gambar 1 langsung dari UI Swagger.

Buat komentar XML dalam metode tindakan pengontrol Anda

Sejauh ini bagus. Dalam dokumen Swagger yang dibuat sebelumnya, tidak ada komentar XML. Jika Anda ingin menampilkan komentar XML di dokumen Swagger, cukup tulis komentar tersebut di metode tindakan pengontrol Anda.

Sekarang mari kita menulis komentar untuk setiap metode tindakan di ValuesController. Berikut adalah versi terbaru dari ValuesController dengan komentar XML untuk setiap metode tindakan.

  [Rute ("api / [controller]")]

    [ApiController]

    kelas publik ValuesController: ControllerBase

    {

        ///

        /// Dapatkan metode tindakan tanpa argumen apa pun

        ///

        ///

        [HttpGet]

        publik ActionResult Dapatkan()

        {

            kembalikan string baru [] {"value1", "value2"};

        }

        ///

        /// Dapatkan metode aksi yang menerima integer sebagai argumen

        ///

        ///

        ///

        [HttpGet ("{id}")]

        publik ActionResult Get (int id)

        {

            mengembalikan "nilai";

        }

        ///

        /// Posting metode tindakan untuk menambahkan data

        ///

        ///

        [HttpPost]

        public void Post (nilai string [FromBody])

        {

        }

        ///

        /// Gunakan metode aksi untuk mengubah data

        ///

        ///

        ///

        [HttpPut ("{id}")]

        public void Put (int id, [FromBody] nilai string)

        {

        }

        ///

        /// Hapus metode tindakan

        ///

        ///

        [HttpDelete ("{id}")]

        public void Hapus (int id)

        {

        }

    }

Aktifkan komentar XML di Swagger

Perhatikan bahwa Swagger tidak menampilkan komentar XML secara default. Anda perlu mengaktifkan fitur ini. Untuk melakukan ini, klik kanan pada Project, pilih Properties, lalu arahkan ke tab Build. Di tab Build, centang opsi "file dokumentasi XML" untuk menentukan lokasi tempat file dokumentasi XML akan dibuat.

Anda juga harus menentukan bahwa komentar XML harus disertakan saat membuat dokumen Swagger dengan menulis kode berikut di metode ConfigureServices.

c.IncludeXmlComments (@ "D: \ Projects \\ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

Dan hanya itu yang perlu Anda lakukan untuk mengaktifkan komentar XML di Swagger.

Setel URL peluncuran untuk aplikasi ke Swagger UI

Anda dapat mengubah URL peluncuran aplikasi Anda untuk menentukan bahwa UI Swagger akan dimuat saat aplikasi diluncurkan. Untuk melakukan ini, klik kanan pada Project dan pilih Properties. Kemudian buka tab Debug. Terakhir, tentukan nilai Launch Browser sebagai swagger seperti yang ditunjukkan pada Gambar 2.

Saat Anda menjalankan aplikasi lagi dan menavigasi ke URL Swagger, Anda akan melihat UI Swagger seperti yang ditunjukkan pada Gambar 3 di bawah. Perhatikan komentar XML di setiap metode API kali ini.

Swashbuckle adalah alat yang hebat untuk menghasilkan dokumen Swagger untuk API Anda. Yang terpenting, Swashbuckle mudah dikonfigurasi dan digunakan. Ada banyak hal yang dapat Anda lakukan dengan Swagger daripada yang telah kita lihat di sini. Anda dapat menyesuaikan UI Swagger menggunakan Cascading Style Sheets, menampilkan nilai enum sebagai nilai string, dan membuat dokumen Swagger yang berbeda untuk berbagai versi API Anda, hanya untuk beberapa nama.