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 webové rozhraní API ASP.NET 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ší automaticky vygenerovat co nejvíce. Pro usnadnění tohoto úkolu poskytuje webové rozhraní API ASP.NET knihovnu pro automatické generování stránek nápovědy za běhu.

Snímek obrazovky stránky nápovědy A S P dot NET A P I, zobrazující dostupné produkty A P I, ze kterých si můžete vybrat, a jejich popisy.

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

Nainstalujte aktualizaci ASP.NET a webových nástrojů 2012.2. 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 k rozhraní API. Všechny soubory kódu na stránce nápovědy jsou umístěny ve složce Oblasti projektu.

Snímek obrazovky s možnostmi nabídky šablony projektu Web API, který zvýrazňuje oblasti a složky stránek nápovědy.

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

Snímek obrazovky domovské stránky, ukazující na klikací písmena A P I, která otevřou odkaz na stránku nápovědy.

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

Snímek obrazovky se stránkou nápovědy souhrnu A P I, zobrazující různé hodnoty A P I a jejich popis

Zobrazení MVC pro tuto stránku je definováno v Areas/HelpPage/Views/Help/Index.cshtml. Na této stránce 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í budu mluvit později.) Pokud přidáte nový kontroler rozhraní API, tabulka se automaticky aktualizuje za běhu.

Sloupec "API" uvádí metodu HTTP a relativní identifikátor URI. Sloupec Popis obsahuje dokumentaci pro každé rozhraní API. Na začátku je dokumentace jenom zástupný text. V další části vám ukážeme, 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 subjektů požadavků a odpovědí.

Snímek obrazovky jedné z hodnot výběru API, zobrazující informace o odpovědi a formáty těla odpovědi.

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čínáte z jiné šablony projektu než ze šablony Webové rozhraní API.

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

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

Pro aplikaci v jazyce Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Existují dva balíčky, jeden pro C# a jeden 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 Areas/HelpPage). Na stránku nápovědy budete muset přidat odkaz ručně. 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 dokumentace XML . Pokud chcete tuto funkci povolit, otevřete soubor Areas/HelpPage/App_Start/HelpPageConfig.cs a odkomentujte následující řádek:

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

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

Snímek obrazovky s rozevírací nabídkou projektu v okně Průzkumníka řešení se zvýrazněnou možností sestavení

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

Snímek obrazovky s dialogovým oknem Výstup zobrazující výstupní cestu a možnost vybrat soubor dokumentace X M L

Dále otevřete kód pro ValuesController kontroler rozhraní API, který je definován v /Controllers/ValuesController.cs. Přidejte do metod kontroleru některé komentáře dokumentace. Napří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:

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

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

Snímek obrazovky tabulky API na stránkách nápovědy, zobrazující dokumentační řetězec v hodnotě a popisu API.

Stránka nápovědy nač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 suroviny pro vytvoření stránky nápovědy. Pro každé rozhraní API obsahuje ApiExplorerpopis rozhraní API, 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á různá 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.

Chcete-li 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, abyste vyloučili celý kontroler.

třída ApiExplorer získá řetězce dokumentace z rozhraní IDocumentationProvider. Jak jste viděli dříve, knihovna Help Pages poskytuje IDocumentationProvider , který získá dokumentaci z řetězců dokumentace XML. Kód se nachází v umístění /Areas/HelpPage/XmlDocumentationProvider.cs. Dokumentaci můžete získat z jiného zdroje napsáním vlastního IDocumentationProvideru. Chcete-li jej připojit, zavolejte rozšiřující metodu SetDocumentationProvider, která je definovaná v HelpPageConfigurationExtensions

ApiExplorer automaticky volá do rozhraní IDocumentationProvider pro získání řetězců dokumentace pro každé rozhraní API. Uloží je do vlastnosti Documentationobjektů ApiDescription a ApiParameterDescription .

Další kroky

Nejste omezeni na stránky nápovědy zobrazené tady. Ve skutečnosti není apiExplorer omezen na vytváření stránek nápovědy. Yao Huang Lin napsal několik skvělých blogových příspěvků, které vám pomůžou začít přemýšlet:

  • Last updated on