Udostępnij za pośrednictwem

Korzystanie z analizatorów internetowego interfejsu API

  • Artykuł

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

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

  • Zwraca nierejestrowany 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

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

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

Analizatory konwencji internetowego interfejsu 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.

analyzer reporting a warning

Analizatory wymagają zestawu Microsoft.NET.Sdk.Web

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

Dodatkowe zasoby