Freigeben über

Verwenden von Web-API-Analyzern

ASP.NET Core stellt ein MVC-Analysepaket bereit, das für die Verwendung mit Web-API-Projekten vorgesehen ist. Die Analysegeräte arbeiten mit Controllern, die mit ApiControllerAttributeAnmerkungen versehen sind, während sie auf Web-API-Konventionen basieren.

Das Analysepaket benachrichtigt Sie über jede Controlleraktion, die:

  • Gibt einen nicht deklarierten Statuscode zurück.
  • Gibt ein nicht deklariertes Erfolgsergebnis zurück.
  • Dokumentiert einen Statuscode, der nicht zurückgegeben wird.
  • Enthält eine explizite Modellüberprüfung.

Verweisen auf das Analysepaket

Die Analysegeräte sind im .NET SDK enthalten. Um den Analyzer in Ihrem Projekt zu aktivieren, schließen Sie die IncludeOpenAPIAnalyzers Eigenschaft in die Projektdatei ein:

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

Analyzer für Web-API-Konventionen

OpenAPI-Dokumente enthalten Statuscodes und Antworttypen, die eine Aktion zurückgeben kann. In ASP.NET Core MVC werden Attribute wie ProducesResponseTypeAttribute und ProducesAttribute zum Dokumentieren einer Aktion verwendet. ASP.NET Core Web API-Dokumentation mit Swagger / OpenAPI geht ausführlicher in die Dokumentation Ihrer Web-API ein.

Einer der Analysegeräte im Paket prüft Controller, die mit ApiControllerAttribute Anmerkungen versehen sind, und identifiziert Aktionen, die ihre Antworten nicht vollständig dokumentieren. Betrachten Sie das folgenden 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);
}

Die vorherige Aktion dokumentiert den HTTP 200-Erfolgsrücklauftyp, dokumentiert jedoch nicht den HTTP 404-Fehlerstatuscode. Der Analyzer meldet die fehlende Dokumentation für den HTTP 404-Statuscode als Warnung. Es wird eine Option zum Beheben des Problems bereitgestellt.

Analysator meldet eine Warnung

Analyzer erfordern Microsoft.NET.Sdk.Web

Analyzer funktionieren nicht mit Bibliotheksprojekten oder Projekten, auf die Sdk="Microsoft.NET.Sdk"verwiesen wird.

Weitere Ressourcen

  • Last updated on