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 ApiControllerAttributepomocí , při vytváření konvencí webového 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 Core 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 ProducesResponseTypeAttribute jsou a ProducesAttribute které se používají k dokumentaci akce. ASP.NET dokumentaci k webovému rozhraní API core s využitím Swaggeru / OpenAPI podrobně zdokumentuje webové rozhraní API.
Jeden z analyzátorů v balíčku kontroluje kontrolery anotované ApiControllerAttribute a identifikuje akce, které zcela nezdokumentují jejich odpovědi. Představte si 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 vrácení úspěchu HTTP 200, ale neoddokumentuje 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 projekty odkazujícími na knihovnu Sdk="Microsoft.NET.Sdk".
