Übung: Anpassen und Erweitern Ihrer OpenAPI-Dokumentation mit XML-Kommentaren und -Anmerkungen

  • 12 Minuten

In dieser Übung ergänzen Sie die Dokumentation, die Entwickler*innen zu Ihrer API angezeigt wird, durch Hinzufügen von Kommentaren und Anmerkungen zu Ihrem Code. Zunächst sehen wir uns an, was Swagger UI standardmäßig bietet.

  1. Wenn Sie die OpenAPI-Definition des Endpunkts unserer API in Swagger UI untersuchen möchten, navigieren Sie in Ihrem Browser zu http://localhost:5000/swagger. Die Ausgabe sollte etwa wie die Folgende aussehen, wenn Sie die Get-Methode auswählen.

    Default Swagger UI for our API.

    Swagger UI stellt einige nützliche Informationen zur API bereit. Dabei werden die Methoden angezeigt, die Sie aufrufen können. In unserem einfachen Fall ist das eine Methode namens PriceFrame. Wie Sie sehen, handelt es sich um einen „HTTP Get“-Vorgang, der zwei Parameter erfordert, nämlich Height und Width. Sie können Ausprobieren auswählen, Werte für Height und Width eingeben und Ausführen auswählen, um den API-Aufruf in Aktion zu sehen.

    Ihre API-Benutzer*innen verfügen immer noch nicht über genügend Informationen, um die Einschränkungen der PriceFrame-Methode zu kennen. Helfen wir ihnen mit ausführlicheren Informationen in Form von XML-Kommentaren.

Hinzufügen von XML-Kommentaren zu Ihrer API

  1. Wechseln Sie zurück zu der Instanz von Visual Studio Code, die Sie in der letzten Übung verwendet haben.

  2. Wenn die Web-API in der letzten Übung noch ausgeführt wird, drücken Sie unter Windows STRG+C oder unter Mac Befehlstaste+C, um sie zu beenden.

  3. Wenn Sie die XML-Dokumentation in Ihrem Projekt aktivieren möchten, aktualisieren Sie die Projektdatei PrintFramerAPI.csproj, und fügen Sie das Tag GenerateDocumentationFile zur vorhandenen <PropertyGroup>-Klasse hinzu, und legen Sie es auf true fest.

    <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

  4. Fügen Sie Startup.cs die folgenden „using“-Anweisungen hinzu.

    using System.Reflection;
using System.IO;

  5. Teilen Sie Swashbuckle in Startup.cs mit, die XML-Dokumentation zu verwenden, indem Sie den Aufruf von AddSwaggerGen() in ConfigureServices aktualisieren.

     public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();

     // Register the Swagger generator, defining 1 or more Swagger documents
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo
         {
             Version = "v1",
             Title = "PrintFramer API",
             Description = "Calculates the cost of a picture frame based on its dimensions.",
             TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"),
             Contact = new OpenApiContact
             {
                 Name = "Your name",
                 Email = string.Empty,
                 Url = new Uri("https://learn.microsoft.com/training")
             }
         });

         // Set the comments path for the Swagger JSON and UI.
         var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
         var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
         c.IncludeXmlComments(xmlPath);
     });
 }

    Im vorigen Code bestimmt die Reflexion den Namen der XML-Datei zum Laden von XML-Kommentaren.

  6. Öffnen Sie im Ordner Controller die Datei PriceFrameController.cs. Fügen Sie den folgenden XML-Kommentarblock oberhalb des HttpGet-Attributs der GetPrice-Methode hinzu. Wenn Sie einer Aktion Kommentare mit drei Schrägstrichen hinzufügen, wird Swagger UI durch Hinzufügen der Beschreibung zum Abschnittsheader erweitert.

     /// <summary>
 /// Returns the price of a frame based on its dimensions.
 /// </summary>
 /// <param name="Height">The height of the frame.</param>
 /// <param name="Width">The width of the frame.</param>
 /// <returns>The price, in dollars, of the picture frame.</returns>
 /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks>
 [HttpGet("{Height}/{Width}")]
 public string GetPrice(string Height, string Width)
 {
     string result;
     result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
     return $"The cost of a {Height}x{Width} frame is ${result}";
 }

  7. Um alle Änderungen zu speichern und sicherzustellen, dass lokal erstellt wird, führen Sie den folgenden Befehl im Visual Studio Code-Terminalfenster aus.

    dotnet build

  8. Um Ihre Änderungen anzuzeigen, führen Sie die ASP.NET Anwendung lokal aus, indem Sie Folgendes im Visual Studio Code-Terminalfenster eingeben:

    dotnet run

  9. Sehen Sie sich die Swagger-Benutzeroberfläche unter http://localhost:5000/swagger noch mal an, und achten Sie auf die durch Ihre XML-Kommentare in der OpenAPI-Dokumentation zusätzlich bereitgestellten Informationen.

    Swagger UI with the final documentation from XML comments for our API.

Hinzufügen von Datenanmerkungen zu Ihrer API

Verwenden Sie Attribute aus dem Microsoft.AspNetCore.Mvc-Namespace, damit Swagger die OpenAPI-Dokumentation verbessern kann.

  1. Wenn die Web-API in der letzten Übung noch ausgeführt wird, drücken Sie unter Windows STRG+C oder unter Mac Befehlstaste+C, um sie zu beenden.

  2. Fügen Sie im API-Controller PriceFrameController.cs über der GetPrice-Definition ein [Produces("text/plain")]-Attribut zum Controller hinzu, um zu zeigen, dass Ihre GetPrice-API für text/plain eine Antwort vom Typ „Inhalt“ unterstützt.

    [HttpGet("{Height}/{Width}")]
[Produces("text/plain")]

    Über die Dropdownliste „Response Content Type“ (Antwortinhaltstyp) wird dieser Inhaltstyp als Standard für die GET-Aktionen des Controllers ausgewählt.

Hinzufügen von Swashbuckle-Anmerkungen zu Ihrer API

Bislang gibt Ihre API den Statuscode 200 zurück, wenn für die gegebenen Rahmenabmessungen ein Preis berechnet werden kann. Beachten Sie in der Beschreibung der GetPrice-Methode den Fall, wenn ein Preis nicht berechnet werden kann.

Die folgenden XML-Kommentare und Datenanmerkungen stellen eine zuverlässigere Möglichkeit dar, Entwicklern die Antworttypen und Fehlercodes mitzuteilen. Swashbuckle und die Swagger-Tools verwenden diese Werte, um eindeutig eine OpenAPI-Beschreibung der erwarteten HTTP-Antwortcodes zu generieren.

Aktualisieren Sie den Filterkonstruktor für HTTP-Verben außerdem so, dass die Name-Eigenschaft eingeschlossen wird, und schließen Sie den operationId-Wert von OpenAPI ein.

  1. Fügen Sie der Datei PriceFrameController.cs die folgende using-Anweisung hinzu.

    using Microsoft.AspNetCore.Http;

  2. Ersetzen Sie in der PriceFrameController.cs-Datei GetPrice durch den folgenden Code und Kommentar.

    /// <summary>
/// Returns the price of a frame based on its dimensions.
/// </summary>
/// <param name="Height">The height of the frame.</param>
/// <param name="Width">The width of the frame.</param>
/// <returns>The price, in dollars, of the picture frame.</returns>
/// <remarks>
/// Sample request:
///
///     Get /api/priceframe/5/10
///
/// </remarks>
/// <response code="200">Returns the cost of the frame in dollars.</response>
/// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response>
[HttpGet("{Height}/{Width}", Name=nameof(GetPrice))]
[Produces("text/plain")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> GetPrice(string Height, string Width)
{
    string result;
    result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
    if (result == "not valid")
    {
        return BadRequest(result);
    }
    else
    {
        return Ok($"The cost of a {Height}x{Width} frame is ${result}");
    }
}

    Dieses Codeupdate bewirkt folgende Änderungen:

    • Die Methode verwendet die Methoden BadRequest() und Ok(), um durch Einfügen des Zeichenfolgenergebnisses in die Antwort eine „BadRequest (400)“-Meldung bzw. einen OK-Status zu erstellen.
    • Die XML-Kommentare beschreiben jeden Statuscode, den diese Methode zurückgeben kann.
    • Das HttpGet-Attribut beinhaltet eine Name-Eigenschaft, um den operationId-Parameter von OpenAPI auszugeben.
    • Die ProducesResponseType-Attribute führen die verschiedenen Antworten auf, die von der Aktion zurückgegeben werden können. Diese Attribute werden wie weiter oben beschrieben mit XML-Kommentaren kombiniert, sodass im generierten Swagger benutzerfreundliche Beschreibungen in die einzelnen Antworten eingefügt werden.

  3. Erstellen Sie die Web-API mit dem folgenden Befehl neu:

    dotnet build

  4. Führen Sie die ASP.NET-Anwendung mit dem folgenden Befehl aus:

    dotnet run

  5. Sehen Sie sich die Swagger-Benutzeroberfläche unter http://localhost:5000/swagger noch mal an, und achten Sie auf die durch diese Anmerkungen zusätzlich bereitgestellten Informationen. Das endgültige Swagger UI-Tool für Ihre API wird in der folgenden Abbildung angezeigt:

    Swagger UI with more documentation from XML comments for our API.

In dieser Übung haben Sie zur wesentlich leichteren Verwendung Ihrer API die Informationen ergänzt, die ein*e Entwickler*in über Ihre API erhält.