Ćwiczenie — dostosowywanie i rozszerzanie dokumentacji interfejsu OpenAPI za pomocą komentarzy XML i adnotacji

  • 12 min

W tym ćwiczeniu wzbogacisz dokumentację, którą deweloper zobaczy o interfejsie API, dodając komentarze i adnotacje do kodu. Najpierw zobaczmy, co domyślnie zwraca narzędzie Swagger UI.

  1. Aby sprawdzić definicję interfejsu OpenAPI punktu końcowego naszego interfejsu API w interfejsie użytkownika struktury Swagger, przejdź do http://localhost:5000/swagger adresu w przeglądarce. Po wybraniu metody Get powinny zostać wyświetlone dane wyjściowe podobne do poniższych.

    Default Swagger UI for our API.

    Narzędzie Swagger UI udostępnia trochę przydatnych informacji o interfejsie API. Przedstawia metody, które można wywołać (w prostym przypadku jedna metoda o nazwie PriceFrame). Zobaczysz, że jest to operacja HTTP Get, która przyjmuje dwa wymagane parametry o nazwie Height (Wysokość) i Width (Szerokość). Aby wyświetlić wywołanie interfejsu API w akcji, możesz wybrać pozycję Wypróbuj, wprowadzić wartości dla pola Wysokość i szerokość, a następnie wybrać pozycję Wykonaj.

    Użytkownicy interfejsu API nadal nie mają wystarczającej ilości informacji, aby poznać ograniczenia metody PriceFrame . Pomóżmy im, podając bardziej szczegółowe informacje za pomocą komentarzy XML.

Dodawanie komentarzy XML do interfejsu API

  1. Wróć do wystąpienia programu Visual Studio Code, które zostało użyte podczas ostatniego ćwiczenia.

  2. Jeśli internetowy interfejs API nadal działa w ostatnim ćwiczeniu, naciśnij klawisze Ctrl+c w systemie Windows lub cmd+c na komputerze Mac, aby go zatrzymać.

  3. Aby aktywować dokumentację XML w projekcie, zaktualizuj plik projektu PrintFramerAPI.csproj, dodaj GenerateDocumentationFile tag do istniejącego <PropertyGroup>elementu i ustaw go na true.

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

  4. Dodaj następujące instrukcje using w pliku Startup.cs.

    using System.Reflection;
using System.IO;

  5. W pliku Startup.cs poinformuj pakiet Swashbuckle o użyciu dokumentacji XML, aktualizując wywołanie AddSwaggerGen() metody w pliku w ConfigureServicespliku .

     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);
     });
 }

    W poprzednim kodzie odbicie określa nazwę pliku XML w celu załadowania komentarzy XML.

  6. W folderze Controllers otwórz plik PriceFrameController.cs. Dodaj następujący blok komentarza XML powyżej atrybutu GetPrice HttpGet metody . Dodawanie do akcji komentarzy z potrójnym ukośnikiem ulepsza wyniki narzędzia Swagger UI przez dodanie opisu do nagłówka sekcji.

     /// <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. Aby zapisać wszystkie zmiany i upewnić się, że kompiluje się lokalnie, uruchom następujące polecenie w oknie terminalu programu Visual Studio Code.

    dotnet build

  8. Aby wyświetlić zmiany, uruchom lokalnie aplikację ASP.NET, wprowadzając następujące polecenie w oknie terminalu programu Visual Studio Code:

    dotnet run

  9. Ponownie przyjrzyj się interfejsowi użytkownika struktury Swagger pod http://localhost:5000/swaggeradresem i obserwuj dodane informacje dostarczone przez komentarze XML do dokumentacji interfejsu OpenAPI.

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

Dodawanie adnotacji do danych do interfejsu API

Aby umożliwić programowi Swagger ulepszenie dokumentacji interfejsu OpenAPI, należy użyć atrybutów z Microsoft.AspNetCore.Mvc przestrzeni nazw.

  1. Jeśli internetowy interfejs API nadal działa w ostatnim ćwiczeniu, naciśnij klawisze Ctrl+c w systemie Windows lub cmd+c na komputerze Mac, aby go zatrzymać.

  2. Aby pokazać, że interfejs GetPrice API obsługuje odpowiedź typu zawartości dla tekstu/zwykłego, w kontrolerze interfejsu API PriceFrameController.cs dodaj [Produces("text/plain")] atrybut powyżej GetPrice definicji.

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

    Ten typ zawartości jest domyślnym typem zawartości akcji GET kontrolera wybranym na liście rozwijanej typu zawartości odpowiedzi.

Dodawanie adnotacji pakietu Swashbuckle do interfejsu API

Do tej pory interfejs API zwraca kod stanu 200, gdy może obliczyć cenę dla danego wymiaru ramki. W opisie GetPrice metody zwróć uwagę na przypadek, gdy nie można obliczyć ceny.

Bardziej niezawodnym sposobem informowania deweloperów o typach odpowiedzi i kodach błędów jest skorzystanie z następujących komentarzy XML i adnotacji do danych. Narzędzia Swashbuckle i Swagger używają tych wartości, aby wyraźnie wygenerować opis interfejsu OpenAPI oczekiwanych kodów odpowiedzi HTTP.

Zaktualizuj również konstruktor filtru czasownika HTTP, aby uwzględnił Name właściwość i uwzględnij wartość interfejsu OpenAPI operationId .

  1. Dodaj następującą instrukcję using do pliku PriceFrameController.cs .

    using Microsoft.AspNetCore.Http;

  2. W pliku PriceFrameController.cs zastąp GetPrice następujący kod i komentarz.

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

    Ta aktualizacja kodu wprowadza następujące zmiany:

    • Metoda używa metod BadRequest() i Ok() w celu utworzenia stanu, odpowiednio, BadRequest (400) i Ok, a także przekazuje wynik w postaci ciągu do odpowiedzi.
    • Komentarze XML opisują każdy kod stanu, który może zwrócić ta metoda.
    • Atrybut HttpGet zawiera Name właściwość do emitowania parametru OpenAPI operationId .
    • Atrybuty ProducesResponseType zawierają listę różnych odpowiedzi, które może zwrócić akcja. Te atrybuty są łączone z komentarzami XML, jak opisaliśmy wcześniej, aby uwzględnić przyjazne dla użytkownika opisy każdej odpowiedzi w wygenerowanych danych programu Swagger

  3. Skompiluj internetowy interfejs API za pomocą następującego polecenia:

    dotnet build

  4. Uruchom aplikację ASP.NET za pomocą następującego polecenia:

    dotnet run

  5. Ponownie przyjrzyj się interfejsowi użytkownika struktury Swagger pod http://localhost:5000/swaggeradresem i obserwuj dodane informacje dostarczone przez te adnotacje. Ostateczne dane narzędzia Swagger UI dla Twojego interfejsu API są widoczne na poniższym obrazie.

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

W tym ćwiczeniu wzbogacono informacje, które deweloper otrzymuje o interfejsie API, co znacznie ułatwia korzystanie z niego.