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.

Jak znázorňuje následující obrázek, Swagger UI přehledně vizualizuje operace a metody.

Uživatelské rozhraní Swagger také umožňuje pracovat a dokonce i 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 když chcete jít ještě dál a poskytnout o něco podrobnější informace? Pokud rozhraní API používáte poprvé, chcete mít co nejvíce informací.

Komentáře XML

Dokumentaci ke svému kódu můžete vytvořit přidáním komentářů XML. Obvykle se komentáře umísťují přímo před blok kódu, ke kterému se vztahují.

/// <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 použité uzly XML:

• 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í.

Po povolení komentářů XML můžou nástroje Swashbuckle zahrnout 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.

Když například přidáte následující poznámku ke kontroleru:

[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á na žádostech a odpovědích. Následující atributy určují, že rozhraní API by mělo používat application/json pouze 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. Přečtěte si další informace o používání konvencí webového rozhraní API.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• operationId Vygenerujte si prostředí pro výrazně lepší využití rozhraní API, včetně dokumentace, generování kódu a integrace s dalšími službami. Automaticky můžete vygenerovat operationId zahrnutím Name vlastnosti do filtru sloves HTTP.

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