Wzbogacanie dokumentacji interfejsu OpenAPI za pomocą komentarzy XML i adnotacji

  • 4 min

Interfejs użytkownika struktury Swagger umożliwia interakcję z zasobami interfejsu API i wizualizowanie ich bez konieczności uzyskiwania dostępu do kodu źródłowego. Graficzna reprezentacja interfejsu API jest automatycznie generowana na podstawie specyfikacji interfejsu OpenAPI i ułatwia innym deweloperom tworzenie aplikacji korzystających z interfejsów API.

Narzędzie Swagger UI przejrzyście wizualizuje operacje i metody, jak pokazano na poniższej ilustracji.

Operations of API in Swagger UI.

Interfejs użytkownika struktury Swagger umożliwia również interakcję, a nawet wypróbowanie każdej operacji.

Interaction with API Operation in Swagger UI.

Automatyczne tworzenie dokumentacji interfejsu API za pomocą narzędzi Swashbuckle i Swagger może pomóc stronom trzecim zrozumieć zasoby interfejsu API. Ale co zrobić, jeśli chcesz udostępnić jeszcze bardziej szczegółowe informacje? W przypadku pierwszego użycia interfejsu API ważny jest dostęp do jak największej ilości informacji.

Komentarze XML

Tworząc dokumentację dla swojego kodu, możesz w niej umieścić komentarze XML. Zazwyczaj należy umieszczać te komentarze bezpośrednio przed blokiem kodu, który komentujesz.

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

Oto używane węzły XML:

  • podsumowanie: ogólne podsumowanie metody/klasy/pola lub jego działania.
  • uwagi: Więcej szczegółów na temat metody/klasy/pola.
  • param: parametr metody i to, co reprezentuje.
  • zwraca: opis zwracanej metody.

Po włączeniu komentarzy XML narzędzia Swashbuckle mogą zawierać komentarze dokumentacji XML w dokumentacji interfejsu OpenAPI i umożliwia wyświetlanie ich w interfejsie użytkownika programu Swagger.

Image showing Swagger UI and added XML Comments.

Adnotacje do danych

Jest to takie samo, jak adnotacje danych. Wystarczy dodać adnotację do modelu, a program Swagger rozszerza dokumentację interfejsu API, aby ją uwzględnić.

Jeśli na przykład dodasz następującą adnotację do kontrolera:

[Produces("application/json")]

... Zobaczysz dodane informacje w interfejsie użytkownika programu Swagger:

Image showing Swagger UI with added content type added to annotations.

Wskazówki

Istnieje kilka adnotacji danych, których należy użyć podczas opisywania interfejsu API.

  • Zidentyfikuj, które content-types interfejs API obsługuje żądania i odpowiedzi. Następujące atrybuty określają, że interfejs API powinien używać application/json tylko typu zawartości w obu kierunkach.

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

  • Zidentyfikuj potencjalne kody odpowiedzi HTTP, które mogą zostać zwrócone do klienta wywołującego. Poniższy atrybut ilustruje interfejs API, który może zwrócić błąd 404 Nie znaleziono.

    [ProducesResponseType(StatusCodes.Status404NotFound)]

    Interfejs API może utworzyć standardowy zestaw kodów odpowiedzi, w takim przypadku można użyć następującego atrybutu, aby określić 200, 400 i 404 zamiast określać poszczególne elementy osobno. Dowiedz się więcej na temat używania konwencji internetowego interfejsu API.

    [ApiConventionMethod(typeof(DefaultApiConventions))]

  • Generowanie elementu w operationId celu znacznego ulepszenia środowiska użycia interfejsu API, w tym dokumentacji, generowania kodu i integracji z innymi usługami. Możesz automatycznie wygenerować element operationId , uwzględniając Name właściwość w filtrze czasownika HTTP.

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