Použití analyzátorů webového rozhraní API

  • Článek
  • 2 min ke čtení

ASP.NET Core verze 2.2 a novější poskytuje balíček analyzátorů MVC určený pro použití s projekty webového rozhraní API. Analyzátory pracují s kontrolery anotacemi s a přitom ApiControllerAttribute při sestavování na základě konvencí webového rozhraní API.

Balíček analyzátorů vás upozorní na všechny akce kontroleru, které:

  • Vrátí nedeklarovaný stavový kód.
  • Vrátí nedeklarovaný výsledek úspěchu.
  • Dokumenty stavový kód, který není vrácen.
  • Zahrnuje explicitní kontrolu ověření modelu.

Odkaz na balíček analyzátoru

Ve ASP.NET Core verze 3.0 nebo novější jsou analyzátory součástí .NET Core SDK. Pokud chcete analyzátor povolit v projektu, IncludeOpenAPIAnalyzers zahrnte vlastnost do souboru projektu:

<PropertyGroup>
 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

Instalace balíčku

Nainstalujte balíček Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet jedním z následujících přístupů:

V okně Správce balíčků konzoly:

  • Přejděte na View Other Windows Správce balíčků Console (Zobrazit > ostatní Windows Správce balíčků > Console).

  • Přejděte do adresáře, ve kterém existuje soubor ApiConventions.csproj.

  • Spusťte následující příkaz:

    Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers

Analyzátory pro konvence webového rozhraní API

Dokumenty OpenAPI obsahují stavové kódy a typy odpovědí, které může akce vrátit. V ASP.NET Core MVC se k zdokumentování akce používají atributy jako ProducesResponseTypeAttribute ProducesAttribute a . ASP.NET Core webového rozhraní API pomocí Swaggeru / OpenAPI podrobnější informace o dokumentování webového rozhraní API.

Jeden z analyzátorů v balíčku kontroluje kontrolery s poznámkami a identifikuje akce, které zcela nezdokumentují ApiControllerAttribute jejich odpovědi. Uvažujte následující příklad:

// GET api/contacts/{guid}
[HttpGet("{id}", Name = "GetById")]
[ProducesResponseType(typeof(Contact), StatusCodes.Status200OK)]
public IActionResult Get(string id)
{
    var contact = _contacts.Get(id);

    if (contact == null)
    {
        return NotFound();
    }

    return Ok(contact);
}

Předchozí akce dokumentuje návratový typ http 200 success, ale nezdokumentuje stavový kód chyby HTTP 404. Analyzátor hlásí chybějící dokumentaci pro stavový kód HTTP 404 jako upozornění. K dispozici je možnost řešení problému.

Analyzátor hlásící upozornění

Další materiály