建立 ASP.NET Web API的說明頁面

本教學課程說明如何在 ASP.NET 4.x 中建立 ASP.NET Web API的說明頁面。

當您建立 Web API 時,建立說明頁面通常很有用,讓其他開發人員知道如何呼叫您的 API。 您可以手動建立所有檔,但最好盡可能自動產生。 為了簡化這項工作,ASP.NET Web API提供程式庫,以在執行時間自動產生說明頁面。

[A P 點 NET A P I 說明] 頁面的螢幕擷取畫面,其中顯示要從中選取的可用 A P I 產品及其描述。

建立 API 說明頁面

安裝ASP.NET 和 Web 工具 2012.2 Update。 此更新會將說明頁面整合到 Web API 專案範本中。

接下來,建立新的 ASP.NET MVC 4 專案,然後選取 Web API 專案範本。 專案範本會建立名為 的 ValuesController 範例 API 控制器。 此範本也會建立 API 說明頁面。 說明頁面的所有程式碼檔案都會放在專案的 [區域] 資料夾中。

Web A P I 專案範本功能表選項的螢幕擷取畫面,其中會四周顯示區域和說明頁面資料夾。

當您執行應用程式時,首頁會包含 API 說明頁面的連結。 在首頁中,相對路徑為 /Help。

首頁的螢幕擷取畫面,指向將開啟說明頁面連結的 A P I 可點選字母。

此連結會帶您前往 API 摘要頁面。

A P I 摘要說明頁面的螢幕擷取畫面,其中顯示不同的 A P I 值及其描述。

此頁面的 MVC 檢視定義在 Areas/HelpPage/Views/Help/Index.cshtml 中。 您可以編輯此頁面來修改版面配置、簡介、標題、樣式等等。

頁面的主要部分是由控制器分組的 API 資料表。 資料表專案是使用 IApiExplorer 介面動態產生的。 (稍後我將會進一步討論此介面。) 如果您新增 API 控制器,資料表會在執行時間自動更新。

「API」 資料行會列出 HTTP 方法和相對 URI。 [描述] 資料行包含每個 API 的檔。 一開始,檔只是預留位置文字。 在下一節中,我將示範如何從 XML 批註新增檔。

每個 API 都有頁面的連結,其中包含更詳細的資訊,包括範例要求和回應主體。

其中一個 A P I 選取值的螢幕擷取畫面,其中顯示回應資訊和回應本文格式。

將說明頁面新增至現有的專案

您可以使用 NuGet 套件管理員,將說明頁面新增至現有的 Web API 專案。 此選項很適合您從與「Web API」範本不同的專案範本開始。

從 [ 工具] 功能表中,選取 [NuGet 套件管理員],然後選取 [ 套件管理員主控台]。 在 [ 套件管理員主控台] 視窗中,輸入下列其中一個命令:

針對 C# 應用程式: Install-Package Microsoft.AspNet.WebApi.HelpPage

針對 Visual Basic 應用程式: Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

C# 有兩個套件,一個用於 C#,另一個用於 Visual Basic。 請務必使用符合您專案的專案。

此命令會安裝必要的元件,並針對位於 Areas/HelpPage 資料夾) (的說明頁面新增 MVC 檢視。 您必須手動新增 [說明] 頁面的連結。 URI 為 /Help。 若要在 razor 檢視中建立連結,請新增下列專案:

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

此外,請務必註冊區域。 在 Global.asax 檔案中,如果下列程式碼尚未存在,請將下列程式碼新增至 Application_Start 方法:

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

    // ...
}

新增 API 檔

根據預設,說明頁面具有檔的預留位置字串。 您可以使用 XML 檔批註 來建立檔。 若要啟用此功能,請開啟 Areas/HelpPage/App_Start/HelpPageConfig.cs 檔案,並取消批註下列這一行:

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

現在啟用 XML 檔。 在 Solution Explorer中,以滑鼠右鍵按一下專案,然後選取 [屬性]。 選取 [ 建置 ] 頁面。

方案總管視窗中專案下拉式功能表的螢幕擷取畫面,其中醒目提示建置選項。

[輸出] 底下,檢查 XML 檔檔。 在編輯方塊中,輸入 「App_Data/XmlDocument.xml」。

[輸出] 對話方塊的螢幕擷取畫面,其中顯示輸出路徑和選取 X M L 檔檔的選項。

接下來,開啟 API 控制器的程式碼 ValuesController ,其定義于 /Controllers/ValuesController.cs 中。 將一些檔批註新增至控制器方法。 例如:

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

注意

提示:如果您將插入號放在方法上方的行上,並輸入三個正斜線,Visual Studio 會自動插入 XML 元素。 然後,您可以填入空白。

現在再次建置並執行應用程式,並流覽至說明頁面。 檔字串應該會出現在 API 資料表中。

說明頁面中 A P I 資料表的螢幕擷取畫面,其中顯示 A P I 值和描述中的檔字串。

說明頁面會在執行時間從 XML 檔案讀取字串。 (當您部署應用程式時,請務必部署 XML 檔案.)

幕後

說明頁面建置於 ApiExplorer 類別之上,這是 Web API 架構的一部分。 ApiExplorer類別提供建立說明頁面的原始資料。 針對每個 API, ApiExplorer 包含描述 API 的 ApiDescription 。 為了達到此目的,「API」會定義為 HTTP 方法和相對 URI 的組合。 例如,以下是一些不同的 API:

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

如果控制器動作支援多個 HTTP 方法, ApiExplorer 會將每個方法視為不同的 API。

若要從 ApiExplorer隱藏 API,請將 ApiExplorerSettings 屬性新增至動作,並將 IgnoreApi 設定為 true。

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

您也可以將此屬性新增至控制器,以排除整個控制器。

ApiExplorer 類別會從 IDocumentationProvider 介面取得檔字串。 如先前所見,說明頁面程式庫提供 IDocumentationProvider ,可從 XML 檔字串取得檔。 程式碼位於 /Areas/HelpPage/XmlDocumentationProvider.cs 中。 您可以撰寫自己的 IDocumentationProvider,以從另一個來源取得檔。 若要將其連線,請呼叫HelpPageConfigurationExtensions中定義的SetDocumentationProvider擴充方法

ApiExplorer 會自動呼叫 IDocumentationProvider 介面,以取得每個 API 的檔字串。 它會將它們儲存在ApiDescriptionApiParameterDescription物件的Documentation屬性中。

後續步驟

您不限於此處顯示的說明頁面。 事實上, ApiExplorer 不限於建立說明頁面。 烏裡哥亞納文 Lin 已撰寫一些絕佳的部落格文章,讓您立即思考: