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

ASP.NET Core poskytuje balíček analyzátorů MVC určený pro použití s projekty webového rozhraní API. Analyzátory pracují s řadiči anotovanými ApiControllerAttribute, přičemž staví na konvencích pro webová rozhraní API.

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

• Vrátí nedelarovaný stavový kód.
• Vrátí nedelarovaný výsledek úspěchu.
• Dokumentuje stavový kód, který se nevrátí.
• Zahrnuje explicitní kontrolu ověření modelu.

Odkaz na balíček analyzátoru

Analyzátory jsou součástí sady .NET SDK. Pokud chcete povolit analyzátor v projektu, zahrňte do IncludeOpenAPIAnalyzers souboru projektu vlastnost:

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

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 dokumentaci akce používají atributy, jako jsou ProducesResponseTypeAttribute a ProducesAttribute. dokumentace k webovému rozhraní API ASP.NET Core s využitím Swaggeru / OpenAPI podává podrobnější pohled na dokumentaci vašeho webového rozhraní API.

Jeden z analyzátorů v balíčku kontroluje kontrolery anotované ApiControllerAttribute a identifikuje akce, které zcela nezdokumentují jejich odpovědi. Podívejte se na 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 typ úspěšného vrácení HTTP 200, ale nedokumentuje stavový kód chyby HTTP 404. Analyzátor hlásí chybějící dokumentaci stavového kódu HTTP 404 jako upozornění. K dispozici je možnost řešení problému.

Analyzátory vyžadují Microsoft.NET.Sdk.Web

Analyzátory nefungují s projekty knihoven nebo s projekty odkazujícími na Sdk="Microsoft.NET.Sdk".

Dodatečné zdroje

• Použití konvencí webového rozhraní API
• Dokumentace k webovému rozhraní API ASP.NET Core s využitím Swaggeru/OpenAPI
• Vytváření webových rozhraní API pomocí ASP.NET Core