Verwenden von Analysetools für Web-APIsUse web API analyzers

ASP.NET Core 2.2 und höher bietet ein MVC-Analysetool-Paket zur Verwendung mit Web-API-Projekten.ASP.NET Core 2.2 and later provides an MVC analyzers package intended for use with web API projects. Die Analysetools arbeiten mit Controllern mit der ApiControllerAttribute-Klasse zusammen und basieren auf Web-API-Konventionen.The analyzers work with controllers annotated with ApiControllerAttribute, while building on web API conventions.

Das Analysetoolpaket unterrichtet Sie über alle Controlleraktionen, auf die Folgendes zutrifft:The analyzers package notifies you of any controller action that:

  • Rückgabe eines nicht deklarierten Statuscodes.Returns an undeclared status code.
  • Rückgabe eines nicht deklarierten Erfolgsergebnisses.Returns an undeclared success result.
  • Dokumentation eines Statuscodes, der nicht zurückgegeben wird.Documents a status code that isn't returned.
  • Eine explizite Modellüberprüfung ist enthalten.Includes an explicit model validation check.

Verweisen auf das AnalysepaketReference the analyzer package

In ASP.NET Core 3.0 oder höher sind die Analysetools im .NET Core SDK enthalten.In ASP.NET Core 3.0 or later, the analyzers are included in the .NET Core SDK. Um das Analysetool im Projekt zu aktivieren, schließen Sie die IncludeOpenAPIAnalyzers-Eigenschaft in die Projektdatei ein:To enable the analyzer in your project, include the IncludeOpenAPIAnalyzers property in the project file:

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

PaketinstallationPackage installation

Installieren Sie das Microsoft.AspNetCore.Mvc.Api.Analyzers-NuGet-Paket mit einem der folgenden Ansätze:Install the Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet package with one of the following approaches:

Aus dem Fenster Paket-Manager-Konsole:From the Package Manager Console window:

  • Wechseln Sie View zu > Weitere Windows - > Paket-Manager-Konsoleanzeigen.Go to View > Other Windows > Package Manager Console.

  • Navigieren Sie zu dem Verzeichnis, in dem die ApiConventions.csproj-Datei gespeichert ist.Navigate to the directory in which the ApiConventions.csproj file exists.

  • Führen Sie den folgenden Befehl aus:Execute the following command:

    Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
    

Analysetools für Web-API-KonventionenAnalyzers for web API conventions

OpenAPI-Dokumente enthalten Statuscodes und Antworttypen die von einer Aktion zurückgegeben werden können.OpenAPI documents contain status codes and response types that an action may return. In ASP.NET Core MVC werden Attribute wie ProducesResponseTypeAttribute und ProducesAttribute verwendet, um eine Aktion zu dokumentieren.In ASP.NET Core MVC, attributes such as ProducesResponseTypeAttribute and ProducesAttribute are used to document an action. Weitere Informationen zum Dokumentieren Ihrer Web-API finden Sie unter ASP.NET Core-Web-API-Hilfeseiten mit Swagger/OpenAPI.ASP.NET Core-Web-API-Hilfeseiten mit Swagger/OpenAPI goes into further detail on documenting your web API.

Eins der Analysetools in dem Paket untersucht Controller mit der ApiControllerAttribute-Klasse und erkennt Aktionen, deren Antworten nicht vollständig dokumentiert werden.One of the analyzers in the package inspects controllers annotated with ApiControllerAttribute and identifies actions that don't entirely document their responses. Betrachten Sie das folgenden Beispiel:Consider the following example:

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

Diese Aktion dokumentiert zwar den HTTP 200-Rückgabetyp „Erfolg“, aber nicht den HTTP 404-Statuscode „Fehler“.The preceding action documents the HTTP 200 success return type but doesn't document the HTTP 404 failure status code. Das Analysetool meldet die fehlende Dokumentation für den HTTP 404-Statuscode als Warnung.The analyzer reports the missing documentation for the HTTP 404 status code as a warning. Es gibt eine Möglichkeit, dieses Problem zu beheben.An option to fix the problem is provided.

Analysetool mit Warnung

Zusätzliche RessourcenAdditional resources