Membuat Halaman Bantuan untuk API Web ASP.NET

2023-06-16

Tutorial dengan kode ini menunjukkan cara membuat halaman bantuan untuk ASP.NET Web API di ASP.NET 4.x.

Saat Anda membuat API web, sering kali berguna untuk membuat halaman bantuan, sehingga pengembang lain akan tahu cara memanggil API Anda. Anda dapat membuat semua dokumentasi secara manual, tetapi lebih baik untuk membuat otomatis sebanyak mungkin. Untuk mempermudah tugas ini, ASP.NET Web API menyediakan pustaka untuk membuat halaman bantuan secara otomatis pada durasi.

Cuplikan layar halaman bantuan A S P dot NET A P I, memperlihatkan produk A P I yang tersedia untuk dipilih dan deskripsinya.

Membuat Halaman Bantuan API

Instal pembaruan ASP.NET dan Web Tools 2012.2. Pembaruan ini mengintegrasikan halaman bantuan ke dalam templat proyek API Web.

Selanjutnya, buat proyek ASP.NET MVC 4 baru dan pilih templat proyek API Web. Templat proyek membuat contoh pengontrol API bernama ValuesController. Templat juga membuat halaman bantuan API. Semua file kode untuk halaman bantuan ditempatkan di folder Area proyek.

Cuplikan layar opsi menu templat proyek Web A P I, melingkari area dan folder halaman bantuan.

Saat Anda menjalankan aplikasi, halaman beranda berisi tautan ke halaman bantuan API. Dari halaman beranda, jalur relatif adalah /Help.

Cuplikan layar halaman beranda, menunjuk ke huruf yang dapat diklik A P I yang akan membuka tautan ke halaman bantuan.

Tautan ini membawa Anda ke halaman ringkasan API.

Cuplikan layar halaman bantuan ringkasan A P I, memperlihatkan nilai A P I yang berbeda dan deskripsinya.

Tampilan MVC untuk halaman ini ditentukan dalam Area/HelpPage/Views/Help/Index.cshtml. Anda dapat mengedit halaman ini untuk mengubah tata letak, pengenalan, judul, gaya, dan sebagainya.

Bagian utama halaman adalah tabel API, yang dikelompokkan menurut pengontrol. Entri tabel dihasilkan secara dinamis, menggunakan antarmuka IApiExplorer . (Saya akan berbicara lebih banyak tentang antarmuka ini nanti.) Jika Anda menambahkan pengontrol API baru, tabel akan diperbarui secara otomatis pada durasi.

Kolom "API" mencantumkan metode HTTP dan URI relatif. Kolom "Deskripsi" berisi dokumentasi untuk setiap API. Awalnya, dokumentasi hanyalah teks tempat penampung. Di bagian berikutnya, saya akan menunjukkan kepada Anda cara menambahkan dokumentasi dari komentar XML.

Setiap API memiliki tautan ke halaman dengan informasi yang lebih rinci, termasuk contoh isi permintaan dan respons.

Cuplikan layar salah satu nilai pilihan A P I, memperlihatkan informasi respons dan format isi respons.

Menambahkan Halaman Bantuan ke Proyek yang Sudah Ada

Anda dapat menambahkan halaman bantuan ke proyek WEB API yang ada dengan menggunakan NuGet Package Manager. Opsi ini berguna untuk Anda mulai dari templat proyek yang berbeda dari templat "API Web".

Dari menu Alat , pilih Pengelola Paket NuGet, lalu pilih Konsol Manajer Paket. Di jendela Konsol Manajer Paket , ketik salah satu perintah berikut:

Untuk aplikasi C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Untuk aplikasi Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Ada dua paket, satu untuk C# dan satu untuk Visual Basic. Pastikan untuk menggunakan yang cocok dengan proyek Anda.

Perintah ini menginstal rakitan yang diperlukan dan menambahkan tampilan MVC untuk halaman bantuan (terletak di folder Area/HelpPage). Anda harus menambahkan tautan secara manual ke halaman Bantuan. URI adalah /Help. Untuk membuat tautan dalam tampilan pisau cukur, tambahkan yang berikut ini:

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

Selain itu, pastikan untuk mendaftarkan area. Dalam file Global.asax, tambahkan kode berikut ke metode Application_Start , jika belum ada:

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

Menambahkan Dokumentasi API

Secara default, halaman bantuan memiliki string tempat penampung untuk dokumentasi. Anda bisa menggunakan komentar dokumentasi XML untuk membuat dokumentasi. Untuk mengaktifkan fitur ini, buka file Area/HelpPage/App_Start/HelpPageConfig.cs dan batalkan komentar baris berikut:

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Sekarang aktifkan dokumentasi XML. Di Penjelajah Solusi, klik kanan proyek dan pilih Properti. Pilih halaman Build .

Cuplikan layar menu drop-down proyek di jendela penjelajah solusi, menyoroti opsi build.

Di bawah Output, periksa file dokumentasi XML. Dalam kotak edit, ketik "App_Data/XmlDocument.xml".

Cuplikan layar kotak dialog Output, memperlihatkan jalur output dan opsi untuk memilih file dokumentasi X M L.

Selanjutnya, buka kode untuk ValuesController pengontrol API, yang ditentukan dalam /Controllers/ValuesController.cs. Tambahkan beberapa komentar dokumentasi ke metode pengontrol. Contohnya:

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

Catatan

Tips: Jika Anda memosisikan tanda sisipan pada baris di atas metode dan mengetik tiga garis miring ke depan, Visual Studio secara otomatis menyisipkan elemen XML. Kemudian Anda dapat mengisi kosong.

Sekarang buat dan jalankan aplikasi lagi, dan navigasikan ke halaman bantuan. String dokumentasi akan muncul dalam tabel API.

Cuplikan layar tabel A P I di halaman bantuan, memperlihatkan string dokumentasi dalam nilai dan deskripsi A P I.

Halaman bantuan membaca string dari file XML pada durasi. (Saat Anda menyebarkan aplikasi, pastikan untuk menyebarkan file XML.)

Di bawah Tenda

Halaman bantuan dibangun di atas kelas ApiExplorer , yang merupakan bagian dari kerangka kerja API Web. Kelas ApiExplorer menyediakan bahan baku untuk membuat halaman bantuan. Untuk setiap API, ApiExplorer berisi ApiDescription yang menjelaskan API. Untuk tujuan ini, "API" didefinisikan sebagai kombinasi metode HTTP dan URI relatif. Misalnya, berikut adalah beberapa API yang berbeda:

GET /api/Products
GET /api/Products/{id}
POST /api/Products

Jika tindakan pengontrol mendukung beberapa metode HTTP, ApiExplorer memperlakukan setiap metode sebagai API yang berbeda.

Untuk menyembunyikan API dari ApiExplorer, tambahkan atribut ApiExplorerSettings ke tindakan dan atur IgnoreApi ke true.

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

Anda juga dapat menambahkan atribut ini ke pengontrol, untuk mengecualikan seluruh pengontrol.

Kelas ApiExplorer mendapatkan string dokumentasi dari antarmuka IDocumentationProvider . Seperti yang Anda lihat sebelumnya, pustaka Halaman Bantuan menyediakan IDocumentationProvider yang mendapatkan dokumentasi dari string dokumentasi XML. Kode ini terletak di /Areas/HelpPage/XmlDocumentationProvider.cs. Anda bisa mendapatkan dokumentasi dari sumber lain dengan menulis IDocumentationProvider Anda sendiri. Untuk menyambungkannya, panggil metode ekstensi SetDocumentationProvider , yang ditentukan dalam HelpPageConfigurationExtensions

ApiExplorer secara otomatis memanggil antarmuka IDocumentationProvider untuk mendapatkan string dokumentasi untuk setiap API. Ini menyimpannya di properti Dokumentasi objek ApiDescription dan ApiParameterDescription .

Langkah berikutnya

Anda tidak terbatas pada halaman bantuan yang diperlihatkan di sini. Bahkan, ApiExplorer tidak terbatas pada pembuatan halaman bantuan. Yao Huang Lin telah menulis beberapa posting blog hebat untuk membuat Anda berpikir di luar kotak:

Bagikan melalui