ASP.NET Web API'si için Yardım Sayfaları Oluşturma

Kod içeren bu öğreticide, ASP.NET 4.x'te ASP.NET Web API'sine yönelik yardım sayfalarının nasıl oluşturulacağı gösterilmektedir.

Web API'sini oluşturduğunuzda, diğer geliştiricilerin API'nizi nasıl çağıracaklarını bilmesi için genellikle bir yardım sayfası oluşturmak yararlı olur. Tüm belgeleri el ile oluşturabilirsiniz, ancak mümkün olduğunca otomatik olarak oluşturmak daha iyidir. Bu görevi kolaylaştırmak için ASP.NET Web API'sinde çalışma zamanında otomatik olarak oluşturulan yardım sayfaları için bir kitaplık sağlanır.

API Yardım Sayfaları Oluşturma

ASP.NET and Web Tools 2012.2 Güncelleştirmesi'ni yükleyin. Bu güncelleştirme, yardım sayfalarını Web API proje şablonuyla tümleştirir.

Ardından, yeni bir MVC 4 projesi ASP.NET oluşturun ve Web API proje şablonunu seçin. Proje şablonu adlı ValuesControllerörnek bir API denetleyicisi oluşturur. Şablon ayrıca API yardım sayfalarını da oluşturur. Yardım sayfasının tüm kod dosyaları projenin Alanlar klasörüne yerleştirilir.

Uygulamayı çalıştırdığınızda giriş sayfasında API yardım sayfasının bağlantısı bulunur. Giriş sayfasında göreli yol /Help şeklindedir.

Bu bağlantı sizi bir API özet sayfasına götürür.

Bu sayfanın MVC görünümü Alanlar/YardımSayfası/Görünümler/Yardım/Index.cshtml içinde tanımlanır. Bu sayfayı düzen, giriş, başlık, stiller vb. değiştirmek için düzenleyebilirsiniz.

Sayfanın ana bölümü, denetleyiciye göre gruplandırılmış bir API tablosudur. Tablo girişleri, IApiExplorer arabirimi kullanılarak dinamik olarak oluşturulur. (Daha sonra bu arabirim hakkında daha fazla konuşacağım.) Yeni bir API denetleyicisi eklerseniz, tablo çalışma zamanında otomatik olarak güncelleştirilir.

"API" sütununda HTTP yöntemi ve göreli URI listelenir. "Açıklama" sütunu her API için belgeler içerir. Başlangıçta, belgeler yalnızca yer tutucu metindir. Sonraki bölümde, XML açıklamalarından belge eklemeyi göstereceğiz.

Her API'nin, örnek istek ve yanıt gövdeleri dahil olmak üzere daha ayrıntılı bilgiler içeren bir sayfaya bağlantısı vardır.

Mevcut Projeye Yardım Sayfaları Ekleme

NuGet Paket Yöneticisi'ne tıklayarak var olan bir Web API'sine yardım sayfaları ekleyebilirsiniz. Bu seçenek, "Web API'si" şablonundan farklı bir proje şablonundan başlamanız için yararlıdır.

Araçlar menüsünde NuGet Paket Yöneticisi'ni ve ardından Paket Yöneticisi Konsolu'nu seçin. Paket Yöneticisi Konsolu penceresinde aşağıdaki komutlardan birini yazın:

C# uygulaması için:Install-Package Microsoft.AspNet.WebApi.HelpPage

Visual Basic uygulaması için:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Biri C# ve diğeri Visual Basic için olan iki paket vardır. Projenizle eşleşeni kullandığınızdan emin olun.

Bu komut gerekli derlemeleri yükler ve yardım sayfaları için MVC görünümlerini ekler (Alanlar/YardımSayfası klasöründe bulunur). Yardım sayfasına el ile bağlantı eklemeniz gerekir. URI,/Help şeklindedir. Razor görünümünde bağlantı oluşturmak için aşağıdakileri ekleyin:

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

Ayrıca, alanları kaydettiğinizden emin olun. Global.asax dosyasında, henüz yoksa Application_Start yöntemine aşağıdaki kodu ekleyin:

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

    // ...
}

API Belgeleri Ekleme

Varsayılan olarak, yardım sayfalarında belgeler için yer tutucu dizeler bulunur. Belgeleri oluşturmak için XML belge açıklamalarını kullanabilirsiniz. Bu özelliği etkinleştirmek için Areas/HelpPage/App_Start/HelpPageConfig.cs dosyasını açın ve aşağıdaki satırın açıklamasını kaldırın:

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

Şimdi XML belgelerini etkinleştirin. Çözüm Gezgini'da projeye sağ tıklayın ve Özellikler'i seçin. Derleme sayfasını seçin.

Çıktı'nın altında XML belge dosyasını denetleyin. Düzenleme kutusuna "App_Data/XmlDocument.xml" yazın.

Ardından, /Controllers/ValuesController.cs içinde tanımlanan API denetleyicisinin kodunu ValuesController açın. Denetleyici yöntemlerine bazı belge açıklamaları ekleyin. Örneğin:

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

Not

İpucu: Şapka işaretini yöntemin üstündeki satıra yerleştirir ve üç eğik çizgi yazarsanız, Visual Studio XML öğelerini otomatik olarak ekler. Ardından boşlukları doldurabilirsiniz.

Şimdi uygulamayı yeniden derleyip çalıştırın ve yardım sayfalarına gidin. Belge dizeleri API tablosunda görünmelidir.

Yardım sayfası, çalışma zamanında XML dosyasındaki dizeleri okur. (Uygulamayı dağıtırken XML dosyasını dağıttığınıza emin olun.)

Kaputun Altında

Yardım sayfaları, Web API çerçevesinin bir parçası olan ApiExplorer sınıfının üzerine kurulmuştur. ApiExplorer sınıfı, yardım sayfası oluşturmak için hammadde sağlar. Her API için ApiExplorer , API'yi açıklayan bir ApiDescription içerir. Bu amaçla, "API" HTTP yöntemi ve göreli URI'nin birleşimi olarak tanımlanır. Örneğin, aşağıda bazı farklı API'ler verilmiştir:

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

Bir denetleyici eylemi birden çok HTTP yöntemini destekliyorsa , ApiExplorer her yöntemi ayrı bir API olarak ele alır.

ApiExplorer'dan bir API'yi gizlemek için, eyleme ApiExplorerSettings özniteliğini ekleyin ve IgnoreApi değerini true olarak ayarlayın.

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

Denetleyicinin tamamını dışlamak için bu özniteliği denetleyiciye de ekleyebilirsiniz.

ApiExplorer sınıfı , IDocumentationProvider arabiriminden belge dizelerini alır. Daha önce gördüğünüz gibi, Yardım Sayfaları kitaplığı XML belge dizelerinden belge alan bir IDocumentationProvider sağlar. Kod /Areas/HelpPage/XmlDocumentationProvider.cs içinde bulunur. Kendi IDocumentationProvider'ınızı yazarak başka bir kaynaktan belge alabilirsiniz. Kablo bağlantısı kurmak için HelpPageConfigurationExtensions içinde tanımlanan SetDocumentationProvider uzantısı yöntemini çağırın

ApiExplorer , her API için belge dizelerini almak için otomatik olarak IDocumentationProvider arabirimini çağırır. Bunları ApiDescription ve ApiParameterDescription nesnelerinin Documentationözelliğinde depolar.

Sonraki Adımlar

Burada gösterilen yardım sayfalarıyla sınırlı değilsiniz. Aslında ApiExplorer , yardım sayfaları oluşturmakla sınırlı değildir. Yao Huang Lin, hemen düşünmenizi sağlamak için harika blog gönderileri yazdı:

• Web API'sini ASP.NET Yardım Sayfasına basit bir Test İstemcisi ekleme
• ASP.NET Web API'si Yardım Sayfasının şirket içinde barındırılan hizmetlerde çalışmasını sağlama
• ASP.NET Web API'sine yönelik tasarım zamanı oluşturma yardım sayfası (veya istemcisi)
• Gelişmiş Yardım Sayfası özelleştirmeleri