Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesem Lernprogramm mit Code wird gezeigt, 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 alle Dokumentationen manuell erstellen, aber es ist besser, so viel wie möglich automatisch zu generieren. Um diese Aufgabe zu vereinfachen, stellt ASP.NET Web-API zur Laufzeit eine Bibliothek zum automatischen Generieren von Hilfeseiten bereit.
Erstellen von API-Hilfeseiten
Installieren Sie ASP.NET- und Webtools 2012.2 Update. 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 Beispiel-API-Controller mit dem Namen 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".
Dieser Link bringt 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 das Layout, die Einführung, den Titel, die Formatvorlagen usw. zu ändern.
Der Hauptteil der Seite ist eine Tabelle mit APIs, gruppiert nach Controller. 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 zur Laufzeit automatisch aktualisiert.
In der Spalte "API" werden die HTTP-Methode und der relative URI aufgelistet. Die Spalte "Beschreibung" enthält Dokumentation für jede API. Zunächst ist die Dokumentation nur Platzhaltertext. Im nächsten Abschnitt zeige ich Ihnen, wie Sie Dokumentationen aus XML-Kommentaren hinzufügen.
Jede API verfügt über einen Link zu einer Seite mit detaillierteren Informationen, einschließlich Beispielanforderungs- und Antworttexten.
Hinzufügen von Hilfeseiten zu einem vorhandenen Projekt
Mithilfe des NuGet-Paket-Managers können Sie Hilfeseiten zu einem vorhandenen Web-API-Projekt hinzufügen. Diese Option ist hilfreich, 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 die Paket-Manager-Konsole aus. Geben Sie im Paket-Manager-Konsolenfenster 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, eine für C# und eine für Visual Basic. Stellen Sie sicher, dass Sie diejenige verwenden, die Ihrem Projekt entspricht.
Mit diesem Befehl werden die erforderlichen Assemblys installiert und die MVC-Ansichten für die Hilfeseiten (im Ordner "Bereiche/Hilfeseite") hinzugefügt. Sie müssen manuell einen Link zur Hilfeseite hinzufügen. Der URI ist /Help. Um einen Link in einer Rasiereransicht 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 sie 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 Kommentare in der folgenden Zeile auf:
config.SetDocumentationProvider(new XmlDocumentationProvider(
HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
Aktivieren Sie nun die XML-Dokumentation. Klicken Sie im 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 ValuesController API-Controller, der 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 Caret in der Zeile oberhalb der Methode positionieren und drei Schrägstriche eingeben, fügt Visual Studio automatisch die XML-Elemente ein. Anschließend können Sie die Leerzeichen ausfüllen.
Erstellen Sie nun die Anwendung, und führen Sie sie erneut aus, und navigieren Sie zu den Hilfeseiten. Die Dokumentationszeichenfolgen sollten in der API-Tabelle angezeigt werden.
Zur Laufzeit werden auf der Hilfeseite die Zeichenfolgen aus der XML-Datei gelesen. (Stellen Sie beim Bereitstellen der Anwendung sicher, dass Sie die XML-Datei bereitstellen.)
Unter der Haube
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. Für jede API enthält ApiExplorer eine ApiDescription , die die API beschreibt. Zu diesem Zweck wird eine "API" als Kombination aus HTTP-Methode und relativen URI definiert. Hier sind beispielsweise einige unterschiedliche APIs:
- GET /api/Products
- GET /api/Products/{id}
- POST /api/Products
Wenn eine Controlleraktion mehrere HTTP-Methoden unterstützt, behandelt apiExplorer jede Methode als unterschiedliche API.
Um eine API aus dem ApiExplorer auszublenden, fügen Sie der Aktion das Attribut "ApiExplorerSettings " 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 aus der IDocumentationProvider-Schnittstelle ab. Wie Sie bereits gesehen haben, stellt die Bibliothek "Hilfeseiten" einen IDocumentationProvider bereit, der Dokumentationen aus XML-Dokumentationszeichenfolgen abruft. Der Code befindet sich in /Areas/HelpPage/XmlDocumentationProvider.cs. Sie können Dokumentationen aus einer anderen Quelle erhalten, indem Sie Ihren eigenen IDocumentationProvider schreiben. Rufen Sie zum Verbinden die SetDocumentationProvider-Erweiterungsmethode auf, die in HelpPageConfigurationExtensions definiert ist.
ApiExplorer ruft automatisch die IDocumentationProvider-Schnittstelle auf, um Dokumentationszeichenfolgen für jede API abzurufen. Sie speichert sie in der Dokumentationseigenschaft der Objekte "ApiDescription " und "ApiParameterDescription" .
Nächste Schritte
Sie sind nicht auf die hier gezeigten Hilfeseiten beschränkt. In der Tat ist ApiExplorer nicht auf das Erstellen von Hilfeseiten beschränkt. Yao Huang Lin hat einige großartige Blogbeiträge geschrieben, um Sie zum Querdenken anzuregen.