Vorherige

Nächste

Ergänzen Ihrer OpenAPI-Dokumentation mit XML-Kommentaren und -Anmerkungen

Abgeschlossen

Mit der Swagger-Benutzeroberfläche können Sie ohne Zugriff auf den Quellcode mit den Ressourcen einer API interagieren und diese visualisieren. Die grafische Darstellung Ihrer API wird automatisch aus Ihrer OpenAPI-Spezifikation generiert. Sie erleichtert anderen Entwickler das Erstellen von Apps, die Ihre APIs nutzen.

Wie in der folgenden Abbildung gezeigt, werden Vorgänge und Methoden durch Swagger UI übersichtlich dargestellt.

Swagger UI ermöglicht es Ihnen außerdem, mit den einzelnen Vorgängen zu interagieren und sie sogar auszuprobieren.

Wenn Ihre API-Dokumentation mit den Swashbuckle- und Swagger-Tools automatisch erstellt wird, hilft das Drittanbietern, sich über die Ressourcen Ihrer API zu informieren. Aber was, wenn Sie einen Schritt weitergehen und noch ausführlichere Informationen bereitstellen möchten? Schließlich werden bei der erstmaligen Verwendung einer API so viele Informationen wie möglich benötigt.

XML-Kommentare

Die Dokumentation für Ihren Code können Sie durch Einbinden von XML-Kommentaren erstellen. In der Regel werden diese Kommentare direkt vor dem zu kommentierenden Codeblock eingefügt.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

Erläuterung zu den verwendeten XML-Knoten:

• summary: Eine kurze Zusammenfassung, was die Methode/Klasse oder das Feld bewirkt bzw. worum es sich jeweils handelt.
• Hinweise: Weitere Details zur Methode/Klasse bzw. zum Feld.
• param: Ein Parameter zur Methode und was er darstellt.
• returns: Eine Beschreibung, was die Methode zurückgibt.

Wenn Sie XML-Kommentare aktiviert haben, kann das Swashbuckle-Tool Ihre XML-Dokumentationskommentare in die OpenAPI-Dokumentation einbinden. Außerdem können Sie sie in der Swagger-Benutzeroberfläche anzeigen.

Datenanmerkungen

Bei Datenanmerkungen verhält es sich ebenso. Wenn Sie Ihrem Modell eine Anmerkung hinzuzufügen, erweitert Swagger die API-Dokumentation, um sie einzuschließen.

Wenn Sie beispielsweise einem Controller die folgende Anmerkung hinzufügen:

[Produces("application/json")]

..., werden die hinzugefügten Informationen in der Swagger-Benutzeroberfläche angezeigt:

Tipps

Es gibt mehrere Datenanmerkungen, die Sie bei der Beschreibung Ihrer API verwenden sollten.

• Ermitteln Sie, welche content-types-Klasen Ihre API bei Anforderungen und Antworten verarbeiten kann. Die folgenden Attribute geben an, dass die API nur den Inhaltstyp application/json in beide Richtungen verwenden soll.

  [Produces("application/json")]
  [Consumes("application/json")]
  

• Ermitteln Sie die möglichen HTTP-Antwortcodes, die beim Aufrufen des Clients zurückgegeben werden können. Das folgende Attribut veranschaulicht eine API, die den Antwortcode „404 Nicht gefunden“ zurückgeben kann.

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  Ihre API kann einen Standardsatz von Antwortcodes erzeugen. In diesem Fall können Sie das folgende Attribut verwenden, um 200, 400 und 404 anzugeben, anstatt alle einzeln angeben zu müssen. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Generieren Sie ein operationId-Objekt, um die Nutzung der API erheblich zu verbessern. Dazu gehören Dokumentation, Codegenerierung und Integration in andere Dienste. Sie können operationId automatisch generieren, indem Sie die Name-Eigenschaft im HTTP-Verbfilter einschließen.

  [HttpGet("{Height}/{Width}", Name="GetPrice")]
  

Weiter