Verwenden von Analysetools für Web-APIs
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.
Analysetools erfordern Microsoft.NET.Sdk.Web
Analysetools arbeiten nicht mit Bibliotheksprojekten oder Projekten, die auf Sdk="Microsoft.NET.Sdk" verweisen.
