Usare gli analizzatori dell'API Web

  • Articolo

ASP.NET Core fornisce un pacchetto di analizzatori MVC destinato all'uso con progetti API Web. Gli analizzatori funzionano con i controller annotati con ApiControllerAttribute, durante la compilazione di convenzioni dell'API Web.

Il pacchetto analizzatori notifica all'utente di qualsiasi azione del controller che:

  • Restituisce un codice di stato non dichiarato.
  • Restituisce un risultato di esito positivo non dichiarato.
  • Documenta un codice di stato che non viene restituito.
  • Include un controllo di convalida esplicito del modello.

Fare riferimento al pacchetto analizzatore

Gli analizzatori sono inclusi in .NET Core SDK. Per abilitare l'analizzatore nel progetto, includere la IncludeOpenAPIAnalyzers proprietà nel file di progetto:

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

Analizzatori per le convenzioni dell'API Web

I documenti OpenAPI contengono i codici di stato e i tipi di risposta che può restituire un'azione. In ASP.NET Core MVC, per documentare un'azione vengono usati attributi come ProducesResponseTypeAttribute e ProducesAttribute. ASP.NET documentazione dell'API Web core con Swagger/OpenAPI illustra in dettaglio la documentazione dell'API Web.

Uno degli analizzatori del pacchetto verifica i controller annotati con ApiControllerAttribute e identifica le azioni che non documentano completamente le relative risposte. Si consideri l'esempio seguente:

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

L'azione precedente documenta il tipo restituito HTTP 200 (operazione riuscita) ma non documenta il codice di stato HTTP 404 (operazione non riuscita). L'analizzatore segnala l'assenza di documentazione per il codice di stato HTTP 404 come un avviso. È disponibile un'opzione per risolvere il problema.

analyzer reporting a warning

Gli analizzatori richiedono Microsoft.NET.Sdk.Web

Gli analizzatori non funzionano con progetti di libreria o progetti che Sdk="Microsoft.NET.Sdk"fanno riferimento a .

Risorse aggiuntive