Condividi tramite

Usare analizzatori di API web

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, basandosi su convenzioni Web API.

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

  • Restituisce un codice di stato non dichiarato.
  • Restituisce un successo 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 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 codici di stato e tipi di risposta che possono essere restituiti da un'azione. In ASP.NET Core MVC, gli attributi come ProducesResponseTypeAttribute e ProducesAttribute vengono usati per documentare un'azione. Documentazione dell'API Web di ASP.NET Core con Swagger/OpenAPI fornisce maggiori dettagli sulla documentazione della tua API Web.

Uno degli analizzatori nel pacchetto controlla i controller annotati con ApiControllerAttribute e identifica le azioni che non documentano completamente le loro 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 di ritorno HTTP 200 di successo ma non documenta il codice di stato di errore HTTP 404. L'analizzatore segnala la documentazione mancante per il codice di stato HTTP 404 come avviso. Viene fornita un'opzione per risolvere il problema.

analizzatore che segnala un avviso

Gli analizzatori richiedono Microsoft.NET.Sdk.Web

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

Risorse aggiuntive

  • Last updated on