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

  • Článek

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.

analyzer reporting a warning

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".

Další prostředky