Verwenden von Analysetools für Web-APIs

  • Artikel

ASP.NET Core bietet ein MVC-Analysetool-Paket zur Verwendung mit Web-API-Projekten. Die Analysetools arbeiten mit Controllern mit der ApiControllerAttribute-Klasse zusammen und basieren auf Web-API-Konventionen.

Das Analysetoolpaket unterrichtet Sie über alle Controlleraktionen, auf die Folgendes zutrifft:

  • Rückgabe eines nicht deklarierten Statuscodes.
  • Rückgabe eines nicht deklarierten Erfolgsergebnisses.
  • Dokumentation eines Statuscodes, der nicht zurückgegeben wird.
  • Eine explizite Modellüberprüfung ist enthalten.

Verweisen auf das Analysepaket

Die Analysetools sind im .NET Core SDK enthalten. Um das Analysetool im Projekt zu aktivieren, schließen Sie die IncludeOpenAPIAnalyzers-Eigenschaft in die Projektdatei ein:

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

Analysetools für Web-API-Konventionen

OpenAPI-Dokumente enthalten Statuscodes und Antworttypen die von einer Aktion zurückgegeben werden können. In ASP.NET Core MVC werden Attribute wie ProducesResponseTypeAttribute und ProducesAttribute verwendet, um eine Aktion zu dokumentieren. ASP.NET Core-Web-API-Dokumentation mit Swagger/OpenAPI geht eingehender auf die Dokumentation Ihrer Web-API ein.

Eins der Analysetools in dem Paket untersucht Controller mit der ApiControllerAttribute-Klasse und erkennt Aktionen, deren Antworten nicht vollständig dokumentiert werden. Betrachten Sie das folgende Beispiel:

// 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“. Das Analysetool meldet die fehlende Dokumentation für den HTTP 404-Statuscode als Warnung. Es gibt eine Möglichkeit, dieses Problem zu beheben.

analyzer reporting a warning

Analysetools erfordern Microsoft.NET.Sdk.Web

Analysetools arbeiten nicht mit Bibliotheksprojekten oder Projekten, die auf Sdk="Microsoft.NET.Sdk" verweisen.

Zusätzliche Ressourcen