Posting ini terakhir diedit oleh QWERTYU pada 2019-4-12 14:24
PerkenalanSetelah menggunakan asp.net Core untuk pengembangan API, menulis dokumentasi API harus menjadi tugas yang menyakitkan bagi pemrogram, tetapi dokumentasi harus ditulis, dan jika tidak ada persyaratan khusus untuk format dokumentasi, dokumentasi akhir sepenuhnya tergantung pada suasana hati pengembang. Atau lebih detail, atau lebih sederhana. Jadi, apakah ada cara cepat dan efisien untuk membangun dokumentasi API? Jawabannya adalah ya, Swagger adalah salah satu alat pembuatan dokumentasi REST API paling populer!
Mengapa menggunakan Swagger sebagai alat pembuatan dokumentasi REST API- Swagger dapat menghasilkan konsol API interaktif yang dapat digunakan pengembang untuk mempelajari dan bereksperimen dengan API dengan cepat.
- Swagger dapat menghasilkan kode SDK klien untuk implementasi di berbagai platform yang berbeda.
- File Swagger dapat dibuat secara otomatis dari komentar kode di berbagai platform.
- Swagger memiliki komunitas yang kuat dengan banyak kontributor yang kuat.
Bagaimana cara menggunakan Swagger untuk menghasilkan dokumentasi API di inti asp.net?- Swashbuckle.AspNetCore adalah proyek sumber terbuka yang menghasilkan dokumentasi Swagger untuk ASP.NET Core Web API.
- NSwag adalah proyek sumber terbuka lainnya untuk mengintegrasikan Swagger UI atau ReDoc ke dalam ASP.NET Core Web API. Ini menyediakan cara untuk menghasilkan kode klien C# dan TypeScript untuk API.
Berikut ini adalah contoh Swashbuckle.AspNetCoreApa saja komponen Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Mengekspos objek SwaggerDocument sebagai model objek Swagger dan middleware untuk titik akhir JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Generator Swagger yang menghasilkan objek SwaggerDocument langsung dari rute, pengontrol, dan model. Ini sering dikombinasikan dengan middleware titik akhir Swagger untuk mengekspos Swagger JSON secara otomatis.
- Swashbuckle.AspNetCore.SwaggerUI: Versi tertanam dari alat UI Swagger. Ini menafsirkan Swagger JSON untuk membangun pengalaman yang dapat disesuaikan dan kaya yang menggambarkan fungsionalitas API Web. Ini termasuk alat pengujian bawaan untuk metode umum.
Bagaimana cara memasang Swashbuckle dengan vs2017?
Cara pertama: instal dari jendela Konsol Pengelola Paket
- Buka Tampilan > Konsol Pengelola Paket Windows > Lainnya
- Arahkan ke direktori yang berisi file TodoApi.csproj
- Silakan jalankan perintah berikut · Instal-Paket Swashbuckle.AspNetCore
-
Cara kedua: Dari dialog Kelola Paket NuGet:- Klik kanan proyek di Penjelajah Solusi > Mengelola Paket NuGet
- Atur Sumber Paket ke nuget.org
- Ketik "Swashbuckle.AspNetCore" di kotak pencarian
- Pilih paket Swashbuckle.AspNetCore dari tab Telusuri dan klik Instal
-
Tambahkan dan konfigurasikan middleware SwaggerPerkenalkan namespace terlebih dahulu: Tambahkan generator Swagger ke koleksi layanan dalam metode Startup.ConfigureServices: diStartup.Konfigurasi, aktifkan middleware untuk menyajikan dokumen JSON yang dihasilkan dan UI Swagger:
Luncurkan aplikasi dan arahkan ke sanahttps://localhost:<port>/sombong/v1/swagger.json。 Dokumentasi yang dihasilkan yang menjelaskan titik akhir ditampilkan dalam format JSON sebagai berikut.
Tersediahttps://localhost:<port>/sombongTemukan UI Swagger. Telusuri dokumentasi API melalui UI Swagger seperti yang ditunjukkan di bawah ini.
Untuk menerapkan akar (http://localhost:<port>/) untuk menyediakan UI Swagger, harap masukkanRutePrefiksProperti diatur ke string kosong:
Penggunaan Swagger Lanjutan (Kustomisasi dan Ekstensi)Gunakan Swagger untuk menambahkan informasi penjelasan ke dokumentasi APIOperasi konfigurasi berikut dilakukan dalam metode AddSwaggerGen, yang menambahkan informasi seperti informasi penulis, lisensi, dan deskripsi: Informasi versi tampilan UI taruhan ditunjukkan pada gambar berikut: Menambahkan komentar ke metode antarmukaMari kita klik API terlebih dahulu, perluas seperti yang ditunjukkan pada gambar di bawah ini, apakah tidak ada komentar, bagaimana cara menambahkan komentar? Tambahkan komentar dokumen dengan tiga/seperti yang ditunjukkan pada gambar di bawah ini, seperti yang ditunjukkan di bawah ini Kemudian jalankan project dan kembali ke swaggerUI untuk melihat apakah komentar muncul Masih belum muncul, jangan khawatir, lihat ke bawah! Mengaktifkan anotasi XMLAnda dapat mengaktifkan anotasi XML menggunakan metode berikut: - Klik kanan proyek di Penjelajah Solusi dan pilih Properti
- Lihat kotak File Dokumen XML di bawah bagian Output tab Build
-
Mengaktifkan anotasi XML memberikan informasi penelusuran kesalahan untuk jenis dan anggota umum yang tidak didokumentasikan. Jika banyak pesan peringatan muncul, misalnya, pesan berikut menunjukkan pelanggaran kode peringatan 1591:
Bagaimana jika Anda menderita OCD dan ingin membatalkan peringatan? Anda dapat membatalkan seperti yang ditunjukkan pada gambar di bawah ini
Perhatikan jalur file dokumen xml yang dihasilkan di atas,
Nota: 1. Untuk sistem operasi Linux atau non-Windows, nama file dan jalur peka huruf besar/kecil. Misalnya, file "SwaggerDemo.xml" berfungsi di Windows, tetapi tidak di CentOS. 2. Untuk mendapatkan jalur aplikasi, disarankan untuk menggunakan AppContext.BaseDirectory untuk mendapatkannya Bangun kembali dan jalankan proyek untuk melihat apakah komentar muncul Dari operasi di atas, dapat diringkas bahwa UI Swagger menampilkan <summary> teks internal dari elemen kode komentar di atas sebagai komentar besar API! Tentu saja, Anda juga dapat menambahkan elemen komentar ke dokumentasi Dapatkan cara. Ini dapat melengkapi <summary> informasi yang ditentukan dalam elemen dan memberikan UI Swagger yang lebih andal. <remarks> Konten elemen dapat berisi teks, JSON, atau XML. Kodenya adalah sebagai berikut: Menguji antarmuka api menggunakan SwaggerUIMari kita debug antarmuka melalui SwaggerUI melalui contoh kecil
- Klik antarmuka API yang perlu diuji, lalu klik tombol "Coba" di kiri dan kanan Parameter
- Masukkan parameter di kotak teks parameter yang muncul, seperti yang ditunjukkan pada gambar berikut, masukkan parameter 2
- Klik tombol Jalankan, dan Respons yang diformat yang ditunjukkan di bawah ini akan muncul, seperti yang ditunjukkan pada gambar di bawah ini
Nah, itu saja untuk tutorial hari ini tentang menggunakan Swagger untuk menghasilkan dokumentasi api di ASP.NET Core WebApi. Saya harap akan membantu Anda mempelajari cara menggunakan Swagger untuk menghasilkan dokumentasi API di ASP.NET Core! ringkasanArtikel ini dimulai dengan masalah menulis dokumentasi API dengan tangan, dan kemudian mengarah ke Swagger, alat yang secara otomatis menghasilkan dokumentasi API! Kemudian, melalui teks dan gambar yang mudah dipahami, kami akan mendemonstrasikan cara menggunakan SwaggerUI untuk menghasilkan dokumentasi API di ASP.NET Core WebApi. Terakhir, saya akan memperkenalkan beberapa penggunaan lanjutan Swagger di ASP.NET Core! Saya harap ini membantu Anda menggunakan Swagger di ASP.NET Core!
| 
Diposting pada 12/04/2019 14.14.46
|
|
|
|
