Korzystanie z analizatorów interfejsu web API

ASP.NET Core udostępnia pakiet analizatorów MVC przeznaczony do użytku z projektami internetowego interfejsu API. Analizatory współpracują z kontrolerami z adnotowanymi elementami ApiControllerAttribute, przy użyciu konwencji internetowego interfejsu API.

Pakiet analizatorów powiadamia o każdej akcji kontrolera, która:

• Zwraca niezdeklarowany kod stanu.
• Zwraca niezadeklarowany wynik powodzenia.
• Dokumentuje kod stanu, który nie jest zwracany.
• Zawiera jawne sprawdzanie poprawności modelu.

Odwołanie do pakietu analizatora danych

Analizatory są uwzględniane w zestawie SDK platformy .NET. Aby włączyć analizator w projekcie, uwzględnij IncludeOpenAPIAnalyzers właściwość w pliku projektu:

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

Analizatory konwencji interfejsu internetowego API

Dokumenty OpenAPI zawierają kody stanu i typy odpowiedzi, które może zwrócić akcja. W ASP.NET Core MVC atrybuty takie jak ProducesResponseTypeAttribute i ProducesAttribute są używane do dokumentowania akcji. ASP.NET Core web API documentation with Swagger / OpenAPI (Dokumentacja internetowego interfejsu API platformy ASP.NET Core za pomocą struktury Swagger/OpenAPI ) zawiera szczegółowe informacje na temat dokumentowania internetowego interfejsu API.

Jeden z analizatorów w pakiecie sprawdza kontrolery z adnotacjami ApiControllerAttribute i identyfikuje akcje, które nie w pełni dokumentują ich odpowiedzi. Rozważmy następujący przykład:

// 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);
}

Poprzednia akcja dokumentuje typ powrotu powodzenia HTTP 200, ale nie dokumentuje kodu stanu błędu HTTP 404. Analizator zgłasza brakującą dokumentację dla kodu stanu HTTP 404 jako ostrzeżenie. Dostępna jest opcja rozwiązania problemu.

Analizatory wymagają zestawu Microsoft.NET.Sdk.Web

Analizatory nie działają z projektami biblioteki ani projektami odwołującymi się do Sdk="Microsoft.NET.Sdk".

Dodatkowe zasoby

• Używanie konwencji internetowego interfejsu API
• Dokumentacja webowego interfejsu API platformy ASP.NET Core przy użyciu Swaggera / OpenAPI
• Tworzenie internetowych interfejsów API za pomocą platformy ASP.NET Core