Skapa hjälpsidor för ASP.NET webb-API

Den här självstudien med kod visar hur du skapar hjälpsidor för ASP.NET webb-API i ASP.NET 4.x.

När du skapar ett webb-API är det ofta användbart att skapa en hjälpsida, så att andra utvecklare vet hur de anropar ditt API. Du kan skapa all dokumentation manuellt, men det är bättre att generera så mycket som möjligt automatiskt. För att göra den här uppgiften enklare tillhandahåller ASP.NET Web API ett bibliotek för automatisk generering av hjälpsidor vid körtid.

Skärmbild av hjälpsidan A S P dot NET A P I som visar tillgängliga A P I-produkter att välja mellan och deras beskrivningar.

Skapa API-hjälpsidor

Installera uppdateringen ASP.NET och Web Tools 2012.2. Den här uppdateringen integrerar hjälpsidor i webb-API-projektmallen.

Skapa sedan ett nytt ASP.NET MVC 4-projekt och välj webb-API-projektmallen. Projektmallen skapar en exempel-API-kontrollant med namnet ValuesController. Mallen skapar även API-hjälpsidorna. Alla kodfiler för hjälpsidan placeras i mappen Områden i projektet.

Skärmbild av menyalternativen för Web A P I-projektmallen, som cirklar runt området och hjälpsidans mappar.

När du kör programmet innehåller startsidan en länk till API-hjälpsidan. Från startsidan är den relativa sökvägen /Hjälp.

Skärmbild av startsidan som pekar på de klickbara A P I-bokstäverna som öppnar länken till hjälpsidan.

Den här länken tar dig till en API-sammanfattningssida.

Skärmbild av A P I-sammanfattningshjälpsidan som visar de olika A P I-värdena och deras beskrivning.

MVC-vyn för den här sidan definieras i Områden/Hjälpsida/Vyer/Hjälp/Index.cshtml. Du kan redigera den här sidan om du vill ändra layout, introduktion, rubrik, format och så vidare.

Huvuddelen av sidan är en tabell med API:er, grupperade efter kontrollant. Tabellposterna genereras dynamiskt med hjälp av gränssnittet IApiExplorer . (Jag ska prata mer om det här gränssnittet senare.) Om du lägger till en ny API-kontrollant uppdateras tabellen automatiskt vid körning.

Kolumnen "API" visar HTTP-metoden och den relativa URI:n. Kolumnen "Beskrivning" innehåller dokumentation för varje API. Till en början är dokumentationen bara platshållartext. I nästa avsnitt visar jag hur du lägger till dokumentation från XML-kommentarer.

Varje API har en länk till en sida med mer detaljerad information, inklusive exempel på begärande- och svarsorgan.

Skärmbild av något av A P I-markeringsvärdena som visar formaten för svarsinformation och svarstext.

Lägga till hjälpsidor i ett befintligt projekt

Du kan lägga till hjälpsidor i ett befintligt webb-API-projekt med hjälp av NuGet Package Manager. Det här alternativet är användbart om du börjar från en annan projektmall än mallen "Webb-API".

På menyn Verktyg väljer du NuGet Package Manager och sedan Package Manager Console. I fönstret Package Manager Console skriver du något av följande kommandon:

För ett C#- program: Install-Package Microsoft.AspNet.WebApi.HelpPage

För ett Visual Basic-program : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Det finns två paket, ett för C# och ett för Visual Basic. Se till att använda den som matchar ditt projekt.

Det här kommandot installerar de nödvändiga sammansättningarna och lägger till MVC-vyerna för hjälpsidorna (finns i mappen Områden/Hjälpsida). Du måste lägga till en länk manuellt på hjälpsidan. URI:n är /Help. Om du vill skapa en länk i en razor-vy lägger du till följande:

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

Se också till att registrera områden. I filen Global.asax lägger du till följande kod i metoden Application_Start , om den inte redan finns där:

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

    // ...
}

Lägga till API-dokumentation

Som standard har hjälpsidorna platshållarsträngar för dokumentation. Du kan använda XML-dokumentationskommentar för att skapa dokumentationen. Om du vill aktivera den här funktionen öppnar du filen Områden/Hjälpsida/App_Start/HelpPageConfig.cs och tar bort kommentaren från följande rad:

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

Aktivera nu XML-dokumentation. Högerklicka på projektet i Solution Explorer och välj Egenskaper. Välj sidan Bygg .

Skärmbild av projektets nedrullningsbara meny i solution explorer-fönstret, som markerar byggalternativet.

Under Utdata kontrollerar du XML-dokumentationsfilen. I redigeringsrutan skriver du "App_Data/XmlDocument.xml".

Skärmbild av dialogrutan Utdata som visar utdatasökvägen och alternativet för att välja X M L-dokumentationsfilen.

Öppna sedan koden för API-kontrollanten ValuesController , som definieras i /Controllers/ValuesController.cs. Lägg till några dokumentationskommentarer till kontrollmetoderna. Som exempel:

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

Anmärkning

Tips: Om du placerar markören på raden ovanför metoden och skriver tre snedstreck, infogar Visual Studio automatiskt de XML-elementen. Sedan kan du fylla i tomrummen.

Skapa och kör programmet igen och gå till hjälpsidorna. Dokumentationssträngarna ska visas i API-tabellen.

Skärmbild av tabellen A P I på hjälpsidorna som visar dokumentationssträngen i A P I-värdet och beskrivningen.

På hjälpsidan läss strängarna från XML-filen vid körning. (När du distribuerar programmet måste du distribuera XML-filen.)

Under huven

Hjälpsidorna bygger på klassen ApiExplorer , som är en del av webb-API-ramverket. Klassen ApiExplorer innehåller råmaterialet för att skapa en hjälpsida. För varje API innehåller ApiExplorer en ApiDescription som beskriver API:et. För detta ändamål definieras ett "API" som en kombination av HTTP-metod och relativ URI. Här är till exempel några distinkta API:er:

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

Om en kontrollantåtgärd stöder flera HTTP-metoder behandlar ApiExplorer varje metod som ett distinkt API.

Om du vill dölja ett API från ApiExplorer lägger du till attributet ApiExplorerSettings i åtgärden och anger IgnoreApi till true.

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

Du kan också lägga till det här attributet till kontrollanten för att exkludera hela kontrollanten.

Klassen ApiExplorer hämtar dokumentationssträngar från gränssnittet IDocumentationProvider . Som du såg tidigare innehåller biblioteket Hjälpsidor en IDocumentationProvider som hämtar dokumentation från XML-dokumentationssträngar. Koden finns i /Areas/HelpPage/XmlDocumentationProvider.cs. Du kan hämta dokumentation från en annan källa genom att skriva din egen IDocumentationProvider. Om du vill koppla den anropar du tilläggsmetoden SetDocumentationProvider , som definieras i HelpPageConfigurationExtensions

ApiExplorer anropar automatiskt IDocumentationProvider-gränssnittet för att hämta dokumentationssträngar för varje API. Den lagrar dem i egenskapen Dokumentation för ApiDescription - och ApiParameterDescription-objekten .

Nästa steg

Du är inte begränsad till de hjälpsidor som visas här. ApiExplorer är faktiskt inte begränsat till att skapa hjälpsidor. Yao Huang Lin har skrivit några bra blogginlägg för att få dig att tänka ur lådan:

  • Last updated on