Utiliser les analyseurs d’API web

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

Le package analyseurs vous avertit de toute action du contrôleur qui :

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

Référencer le package de l’analyseur

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

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

Analyseurs pour les conventions d’API web

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

Un des analyseurs du package inspecte les contrôleurs annotés avec ApiControllerAttribute et identifie les actions qui ne document 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 avec 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 sous la forme d’un avertissement. Une option pour résoudre le problème est fournie.

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

Les analyseurs ne fonctionnent pas avec les projets de bibliothèque ou les projets faisant référence à 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