Obohacení dokumentace k OpenAPI pomocí komentářů XML a poznámek

Dokončeno

Swagger UI umožňuje pracovat s prostředky rozhraní API a vizualizovat je bez nutnosti přístupu ke zdrojovému kódu. Grafické znázornění rozhraní API se automaticky generuje ze specifikace OpenAPI a usnadňuje ostatním vývojářům vytváření aplikací, které využívají vaše rozhraní API.

Uživatelské rozhraní Swagger vizualizuje operace a metody jasně, jak je znázorněno na následujícím obrázku.

Uživatelské rozhraní Swagger také umožňuje interagovat a dokonce si vyzkoušet každou operaci.

Automatické vytváření dokumentace k rozhraní API pomocí nástrojů Swashbuckle a Swagger může třetím stranám pomoct porozumět prostředkům vašeho rozhraní API. Ale co kdybyste chtěli jít o něco dál a poskytnout ještě podrobnější informace? Pokud rozhraní API používáte poprvé, potřebujete co nejvíce informací.

Komentáře XML

Dokumentaci pro kód můžete vytvořit zahrnutím komentářů XML. Tyto komentáře byste obvykle umístili přímo před blok kódu, ke kterému komentujete.

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

Tady jsou uzly XML, které se používají:

• summary: Souhrnný souhrn toho, co metoda, třída nebo pole je nebo dělá.
• poznámky: Další podrobnosti o metodě, třídě nebo poli.
• parametr: Parametr metody a to, co představuje.
• returns: Popis toho, co metoda vrací.

Jakmile povolit komentáře XML, nástroje Swashbuckle můžou obsahovat vaše komentáře dokumentace XML do dokumentace OpenAPI a umožní vám ho zobrazit v uživatelském rozhraní Swagger.

Datové poznámky

Je to stejné s datovými poznámkami. Stačí do modelu přidat poznámku a Swagger rozšíří dokumentaci k rozhraní API, aby ji zahrnula.

Pokud například přidáte do kontroleru následující poznámku:

[Produces("application/json")]

... Zobrazí se přidané informace v uživatelském rozhraní Swagger:

Tipy

Při popisu rozhraní API byste měli použít několik datových poznámek.

• Určete, které content-types vaše rozhraní API zpracovává požadavky a odpovědi. Následující atributy určují, že rozhraní API by mělo používat pouze application/json typ obsahu v obou směrech.

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

• Identifikujte potenciální kódy odpovědí HTTP, které by se mohly vrátit volajícímu klientovi. Následující atribut znázorňuje rozhraní API, které by mohlo vrátit hodnotu 404 Nenalezena.

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  Vaše rozhraní API může vytvořit standardní sadu kódů odpovědí, v takovém případě můžete použít následující atribut k zadání hodnot 200, 400 a 404 místo jednotlivých. Další informace o si můžete přečíst s použitím konvencí webového rozhraní API.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Vygenerujte operationId, aby se výrazně zlepšilo využití rozhraní API, včetně dokumentace, generování kódu a integrace s dalšími službami. operationId můžete automaticky vygenerovat zahrnutím vlastnosti Name do filtru příkazů HTTP.

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