Utiliser des analyseurs d’API web

ASP.NET Core fournit un package d’analyseurs MVC destiné à être utilisé avec des projets d’API web. Les analyseurs fonctionnent avec des contrôleurs annotés avec ApiControllerAttribute, tout en utilisant des conventions d’API web.

Le package d’analyseurs vous informe d’une action de contrôleur qui :

• Retourne un code d’état non déclaré.
• Retourne un résultat de réussite non déclaré.
• Documente un code de statut qui n’est pas renvoyé.
• Inclut une vérification de validation de modèle explicite.

Référencer le package d’analyseur

Les analyseurs sont inclus dans le Kit de développement logiciel (SDK) .NET. Pour activer l’analyseur dans votre projet, incluez la IncludeOpenAPIAnalyzers propriété dans le fichier projet :

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

Analyseurs pour les conventions d’API web

Les documents OpenAPI contiennent des codes d’état et des types de réponse qu’une action peut retourner. Dans ASP.NET Core MVC, les attributs tels que ProducesResponseTypeAttribute et ProducesAttribute sont utilisés pour documenter une action. La documentation de l’API web ASP.NET Core avec Swagger / OpenAPI explique plus en détail comment documenter votre API web.

L’un des analyseurs du package inspecte les contrôleurs annotés avec ApiControllerAttribute et identifie les actions qui ne documentent pas entièrement leurs réponses. Prenons l’exemple suivant :

// 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’action précédente documente le type de retour de réussite HTTP 200, mais ne documente pas le code d’état d’échec HTTP 404. L’analyseur signale la documentation manquante pour le code d’état HTTP 404 en tant qu’avertissement. Une option permettant de résoudre le problème est fournie.

Les analyseurs nécessitent Microsoft.NET.Sdk.Web

Les analyseurs ne fonctionnent pas avec des projets de bibliothèque ou des projets référençant Sdk="Microsoft.NET.Sdk".

Ressources supplémentaires

• Utiliser les conventions d’API web
• Documentation de l’API web ASP.NET Core avec Swagger/OpenAPI
• Créer des API web avec ASP.NET Core