Delen via

Web-API-analyse gebruiken

ASP.NET Core biedt een MVC Analyzers-pakket dat is bedoeld voor gebruik met web-API-projecten. De analyzers werken met controllers die zijn geannoteerd met ApiControllerAttribute, terwijl ze bouwen op web API-conventies.

Met het analysepakket wordt u op de hoogte gesteld van een controlleractie die:

  • Retourneert een niet-declaratieve statuscode.
  • Retourneert een niet-gedeclareerd succesresultaat.
  • Documenteert een statuscode die niet wordt geretourneerd.
  • Bevat een expliciete modelvalidatiecontrole.

Verwijzen naar het analysepakket

De analyses zijn opgenomen in de .NET SDK. Als u de analyse in uw project wilt inschakelen, neemt u de IncludeOpenAPIAnalyzers eigenschap op in het projectbestand:

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

Analyses voor web-API-conventies

OpenAPI-documenten bevatten statuscodes en antwoordtypen die een actie kan retourneren. In ASP.NET Core MVC worden kenmerken zoals ProducesResponseTypeAttribute en ProducesAttribute gebruikt om een actie te documenteren. ASP.NET Core web-API-documentatie met Swagger/OpenAPI gaat dieper in op het documenteren van uw web-API.

Een van de analyzers in het pakket inspecteert controllers geannoteerd met ApiControllerAttribute en identificeert acties die hun antwoorden niet volledig documenteren. Bekijk het volgende voorbeeld:

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

De voorgaande actie documenteert het retourtype HTTP 200,maar documenteert niet de HTTP 404-foutcode. De analyzer rapporteert de ontbrekende documentatie voor de HTTP 404-statuscode als waarschuwing. Er is een optie beschikbaar om het probleem op te lossen.

analyser die een waarschuwing rapporteert

Analyzers vereisen Microsoft.NET.Sdk.Web

Analyzers werken niet met bibliotheekprojecten of projecten waarnaar wordt verwezen Sdk="Microsoft.NET.Sdk".

Additional resources