Vytváření stránek nápovědy pro webové rozhraní API ASP.NET

Tento kurz s kódem ukazuje, jak vytvořit stránky nápovědy pro ASP.NET webové rozhraní API v ASP.NET 4.x.

Při vytváření webového rozhraní API je často užitečné vytvořit stránku nápovědy, aby ostatní vývojáři věděli, jak volat vaše rozhraní API. Veškerou dokumentaci můžete vytvořit ručně, ale je lepší co nejvíce automaticky vygenerovat. Pro usnadnění této úlohy poskytuje ASP.NET webové rozhraní API knihovnu pro automatické generování stránek nápovědy za běhu.

Vytváření stránek nápovědy rozhraní API

Nainstalujte ASP.NET and Web Tools 2012.2 Update. Tato aktualizace integruje stránky nápovědy do šablony projektu webového rozhraní API.

Dále vytvořte nový projekt ASP.NET MVC 4 a vyberte šablonu projektu webového rozhraní API. Šablona projektu vytvoří ukázkový kontroler rozhraní API s názvem ValuesController. Šablona také vytvoří stránky nápovědy rozhraní API. Všechny soubory kódu pro stránku nápovědy jsou umístěny ve složce Oblasti projektu.

Při spuštění aplikace obsahuje domovská stránka odkaz na stránku nápovědy rozhraní API. Na domovské stránce je relativní cesta /Help.

Tento odkaz vás přenese na stránku souhrnu rozhraní API.

Zobrazení MVC pro tuto stránku je definováno v části Areas/HelpPage/Views/Help/Index.cshtml. Úpravou této stránky můžete upravit rozložení, úvod, název, styly atd.

Hlavní částí stránky je tabulka rozhraní API seskupených podle kontroleru. Položky tabulky se generují dynamicky pomocí rozhraní IApiExplorer . (O tomto rozhraní se budeme podrobněji bavit později.) Pokud přidáte nový kontroler rozhraní API, tabulka se automaticky aktualizuje za běhu.

Ve sloupci "API" je uvedena metoda HTTP a relativní identifikátor URI. Sloupec Popis obsahuje dokumentaci pro každé rozhraní API. Zpočátku je dokumentace jenom zástupný text. V další části vám ukážu, jak přidat dokumentaci z komentářů XML.

Každé rozhraní API obsahuje odkaz na stránku s podrobnějšími informacemi, včetně ukázkových těl požadavků a odpovědí.

Přidání stránek nápovědy do existujícího projektu

Stránky nápovědy můžete přidat do existujícího projektu webového rozhraní API pomocí Správce balíčků NuGet. Tato možnost je užitečná, když začnete s jinou šablonou projektu, než je šablona webového rozhraní API.

V nabídce Nástroje vyberte Správce balíčků NuGet a pak vyberte Konzola Správce balíčků. V okně Konzola Správce balíčků zadejte jeden z následujících příkazů:

Pro aplikaci v jazyce C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Pro aplikaci Visual Basicu : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Existují dva balíčky, jeden pro jazyk C# a druhý pro Visual Basic. Nezapomeňte použít ten, který odpovídá vašemu projektu.

Tento příkaz nainstaluje potřebná sestavení a přidá zobrazení MVC pro stránky nápovědy (umístěné ve složce Oblasti/HelpPage). Budete muset ručně přidat odkaz na stránku nápovědy. Identifikátor URI je /Help. Pokud chcete vytvořit odkaz v zobrazení razor, přidejte následující:

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

Nezapomeňte také zaregistrovat oblasti. V souboru Global.asax přidejte do metody Application_Start následující kód, pokud tam ještě není:

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

    // ...
}

Přidání dokumentace k rozhraní API

Ve výchozím nastavení mají stránky nápovědy zástupné řetězce pro dokumentaci. K vytvoření dokumentace můžete použít komentáře k dokumentaci XML . Pokud chcete tuto funkci povolit, otevřete soubor Areas/HelpPage/App_Start/HelpPageConfig.cs a zrušte komentář na následujícím řádku:

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

Teď povolte dokumentaci XML. V Průzkumník řešení klikněte pravým tlačítkem na projekt a vyberte Vlastnosti. Vyberte stránku Sestavení .

V části Výstup zkontrolujte soubor dokumentace XML. Do textového pole zadejte "App_Data/XmlDocument.xml".

Dále otevřete kód kontroleru ValuesController rozhraní API, který je definován v souboru /Controllers/ValuesController.cs. Přidejte některé komentáře k dokumentaci k metodám kontroleru. Příklad:

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

Poznámka

Tip: Pokud umístíte kurzor na řádek nad metodu a zadáte tři lomítka, Visual Studio automaticky vloží elementy XML. Potom můžete vyplnit prázdné hodnoty.

Teď aplikaci znovu sestavte a spusťte a přejděte na stránky nápovědy. Řetězce dokumentace by se měly zobrazit v tabulce rozhraní API.

Stránka nápovědy přečte řetězce ze souboru XML za běhu. (Při nasazování aplikace nezapomeňte nasadit soubor XML.)

Pod kapotou

Stránky nápovědy jsou postavené na třídě ApiExplorer , která je součástí architektury webového rozhraní API. Třída ApiExplorer poskytuje surovinu pro vytvoření stránky nápovědy. Pro každé rozhraní API obsahuje ApiExplorerpopis apiDescription , který popisuje rozhraní API. Pro tento účel je rozhraní API definováno jako kombinace metody HTTP a relativního identifikátoru URI. Tady jsou například některá odlišná rozhraní API:

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

Pokud akce kontroleru podporuje více metod HTTP, apiExplorer zachází s každou metodou jako s odlišným rozhraním API.

Pokud chcete skrýt rozhraní API z ApiExplorer, přidejte do akce atribut ApiExplorerSettings a nastavte IgnoreApi na true.

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

Tento atribut můžete také přidat do kontroleru a vyloučit tak celý kontroler.

Třída ApiExplorer získá řetězce dokumentace z rozhraní IDocumentationProvider . Jak jste viděli dříve, knihovna stránek nápovědy poskytuje IDocumentationProvider , který získává dokumentaci z řetězců dokumentace XML. Kód se nachází v souboru /Areas/HelpPage/XmlDocumentationProvider.cs. Dokumentaci můžete získat z jiného zdroje napsáním vlastního IDocumentationProvider. Pokud ho chcete připojit, zavolejte metodu rozšíření SetDocumentationProvider definovanou v HelpPageConfigurationExtensions.

ApiExplorer automaticky volá rozhraní IDocumentationProvider , aby získalo řetězce dokumentace pro každé rozhraní API. Ukládá je ve vlastnosti Documentationobjektů ApiDescription a ApiParameterDescription .

Další kroky

Nejste omezeni na zde zobrazené stránky nápovědy. ApiExplorer se ve skutečnosti neomezuje na vytváření stránek nápovědy. Yao Huang Lin napsal některé skvělé blogové příspěvky, které vám umožní přemýšlet mimo krabici:

• Přidání jednoduchého testovacího klienta na stránku nápovědy k webovému rozhraní API ASP.NET
• Zajištění fungování stránky nápovědy k webovému rozhraní API pro ASP.NET ve službách v místním prostředí
• Generování stránky nápovědy (nebo klienta) pro ASP.NET webové rozhraní API v době návrhu
• Upřesnit přizpůsobení stránky nápovědy