Erstellen von Hilfeseiten für ASP.NET-Web-API

In diesem Tutorial mit Code erfahren Sie, wie Sie Hilfeseiten für ASP.NET-Web-API in ASP.NET 4.x erstellen.

Wenn Sie eine Web-API erstellen, ist es häufig hilfreich, eine Hilfeseite zu erstellen, damit andere Entwickler wissen, wie Sie Ihre API aufrufen. Sie könnten die gesamte Dokumentation manuell erstellen, aber es ist besser, so viel wie möglich automatisch zu generieren. Um diese Aufgabe zu vereinfachen, stellt ASP.NET-Web-API eine Bibliothek zum automatischen Generieren von Hilfeseiten zur Laufzeit bereit.

Erstellen von API-Hilfeseiten

Installieren Sie ASP.NET and Web Tools Update 2012.2. Dieses Update integriert Hilfeseiten in die Web-API-Projektvorlage.

Erstellen Sie als Nächstes ein neues ASP.NET MVC 4-Projekt, und wählen Sie die Web-API-Projektvorlage aus. Die Projektvorlage erstellt einen API-Beispielcontroller namens ValuesController. Die Vorlage erstellt auch die API-Hilfeseiten. Alle Codedateien für die Hilfeseite werden im Ordner Bereiche des Projekts platziert.

Wenn Sie die Anwendung ausführen, enthält die Startseite einen Link zur API-Hilfeseite. Auf der Startseite lautet der relative Pfad /Help.

Über diesen Link gelangen Sie zu einer API-Zusammenfassungsseite.

Die MVC-Ansicht für diese Seite ist in Areas/HelpPage/Views/Help/Index.cshtml definiert. Sie können diese Seite bearbeiten, um Layout, Einführung, Titel, Stile usw. zu ändern.

Der Standard Teil der Seite ist eine Tabelle mit APIs, die nach Controller gruppiert ist. Die Tabelleneinträge werden dynamisch mithilfe der IApiExplorer-Schnittstelle generiert. (Ich werde später mehr über diese Schnittstelle sprechen.) Wenn Sie einen neuen API-Controller hinzufügen, wird die Tabelle automatisch zur Laufzeit aktualisiert.

In der Spalte "API" sind die HTTP-Methode und der relative URI aufgeführt. Die Spalte "Beschreibung" enthält dokumentation für jede API. Zunächst ist die Dokumentation nur Platzhaltertext. Im nächsten Abschnitt wird gezeigt, wie Sie Dokumentation aus XML-Kommentaren hinzufügen.

Jede API verfügt über einen Link zu einer Seite mit ausführlicheren Informationen, einschließlich Beispielanforderungs- und Antworttexten.

Hinzufügen von Hilfeseiten zu einem vorhandenen Projekt

Sie können hilfeseiten zu einem vorhandenen Web-API-Projekt hinzufügen, indem Sie den NuGet-Paket-Manager verwenden. Diese Option ist nützlich, wenn Sie mit einer anderen Projektvorlage als der Vorlage "Web-API" beginnen.

Wählen Sie im Menü Extras die Option NuGet-Paket-Manager und dann Paket-Manager-Konsole aus. Geben Sie im Fenster Paket-Manager-Konsole einen der folgenden Befehle ein:

Für eine C#- Anwendung: Install-Package Microsoft.AspNet.WebApi.HelpPage

Für eine Visual Basic-Anwendung : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Es gibt zwei Pakete, eines für C# und eines für Visual Basic. Stellen Sie sicher, dass Sie die verwenden, die Ihrem Projekt entspricht.

Dieser Befehl installiert die erforderlichen Assemblys und fügt die MVC-Ansichten für die Hilfeseiten (im Ordner Areas/HelpPage) hinzu. Sie müssen manuell einen Link zur Hilfeseite hinzufügen. Der URI ist /Help. Um einen Link in einer Razor-Ansicht zu erstellen, fügen Sie Folgendes hinzu:

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

Stellen Sie außerdem sicher, dass Sie Bereiche registrieren. Fügen Sie in der Datei Global.asax den folgenden Code zur Application_Start-Methode hinzu, falls er noch nicht vorhanden ist:

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

    // ...
}

Hinzufügen der API-Dokumentation

Standardmäßig verfügen die Hilfeseiten über Platzhalterzeichenfolgen für die Dokumentation. Sie können XML-Dokumentationskommentare verwenden, um die Dokumentation zu erstellen. Um dieses Feature zu aktivieren, öffnen Sie die Datei Areas/HelpPage/App_Start/HelpPageConfig.cs, und heben Sie die Auskommentierung der folgenden Zeile auf:

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

Aktivieren Sie nun die XML-Dokumentation. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus. Wählen Sie die Seite Erstellen aus.

Überprüfen Sie unter Ausgabe die XML-Dokumentationsdatei. Geben Sie im Bearbeitungsfeld "App_Data/XmlDocument.xml" ein.

Öffnen Sie als Nächstes den Code für den API-Controller, der ValuesController in /Controllers/ValuesController.cs definiert ist. Fügen Sie den Controllermethoden einige Dokumentationskommentare hinzu. Beispiel:

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

Hinweis

Tipp: Wenn Sie das Caretzeichen in der Zeile über der -Methode positionieren und drei Schrägstriche eingeben, fügt Visual Studio die XML-Elemente automatisch ein. Dann können Sie die Leerzeichen ausfüllen.

Erstellen Sie nun die Anwendung, führen Sie sie erneut aus, und navigieren Sie zu den Hilfeseiten. Die Dokumentationszeichenfolgen sollten in der API-Tabelle angezeigt werden.

Die Hilfeseite liest die Zeichenfolgen zur Laufzeit aus der XML-Datei. (Stellen Sie beim Bereitstellen der Anwendung sicher, dass Sie die XML-Datei bereitstellen.)

Im Hintergrund

Die Hilfeseiten basieren auf der ApiExplorer-Klasse , die Teil des Web-API-Frameworks ist. Die ApiExplorer-Klasse stellt das Rohmaterial zum Erstellen einer Hilfeseite bereit. ApiExplorer enthält für jede API eine ApiDescription, die die API beschreibt. Zu diesem Zweck wird eine "API" als Kombination aus HTTP-Methode und relativem URI definiert. Hier sind beispielsweise einige unterschiedliche APIs aufgeführt:

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

Wenn eine Controlleraktion mehrere HTTP-Methoden unterstützt, behandelt der ApiExplorer jede Methode als eigene API.

Um eine API aus dem ApiExplorer auszublenden, fügen Sie der Aktion das ApiExplorerSettings-Attribut hinzu, und legen Sie IgnoreApi auf true fest.

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

Sie können dieses Attribut auch dem Controller hinzufügen, um den gesamten Controller auszuschließen.

Die ApiExplorer-Klasse ruft Dokumentationszeichenfolgen von der IDocumentationProvider-Schnittstelle ab. Wie Sie zuvor gesehen haben, stellt die Hilfeseitenbibliothek einen IDocumentationProvider bereit, der Dokumentation aus XML-Dokumentationszeichenfolgen abruft. Der Code befindet sich in /Areas/HelpPage/XmlDocumentationProvider.cs. Sie können die Dokumentation aus einer anderen Quelle abrufen, indem Sie Ihren eigenen IDocumentationProvider schreiben. Rufen Sie zum Verknüpfen die SetDocumentationProvider-Erweiterungsmethode auf, die in HelpPageConfigurationExtensions definiert ist.

ApiExplorer ruft automatisch die IDocumentationProvider-Schnittstelle auf, um Dokumentationszeichenfolgen für jede API abzurufen. Sie werden in der Documentation-Eigenschaft der Objekte ApiDescription und ApiParameterDescription gespeichert.

Nächste Schritte

Sie sind nicht auf die hier gezeigten Hilfeseiten beschränkt. Tatsächlich ist ApiExplorer nicht auf das Erstellen von Hilfeseiten beschränkt. Yao Huang Lin hat einige großartige Blogbeiträge geschrieben, um Sie zum Nachdenken zu bringen:

• Hinzufügen eines einfachen Testclients zur ASP.NET-Web-API Hilfeseite
• So funktioniert ASP.NET-Web-API Hilfeseite für selbstgehostete Dienste
• Entwurfszeitgenerierung der Hilfeseite (oder des Clients) für ASP.NET-Web-API
• Erweiterte Anpassungen der Hilfeseite