Enrichissement de la documentation OpenAPI avec des annotations et des commentaires XML

Effectué

Swagger UI vous permet d’interagir avec les ressources d’une API et de les visualiser sans accéder au code source. La représentation graphique de votre API est générée automatiquement à partir de votre spécification OpenAPI, ce qui permet aux autres développeurs de créer plus facilement des applications utilisant vos API.

Swagger UI offre une visualisation claire des opérations et des méthodes, comme le montre l’image suivante.

Swagger UI vous permet aussi d’interagir avec les opérations et même de les essayer.

En créant automatiquement la documentation de votre API avec les outils Swashbuckle et Swagger, vous pouvez aider les tiers à comprendre les ressources de votre API. Mais comment faire si vous voulez aller un peu plus loin et fournir des informations encore plus détaillées ? Quand vous utilisez une API pour la première fois, vous souhaitez le plus d’informations possible.

Commentaires XML

Vous pouvez créer de la documentation pour votre code en incluant des commentaires XML. Ceux-ci sont généralement placés juste avant le bloc de code que vous souhaitez commenter.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

Voici les nœuds XML utilisés :

• summary : présentation générale couvrant la nature ou le rôle de la méthode, de la classe ou du champ.
• remarks : Détails supplémentaires sur la méthode, la classe ou le champ.
• param : paramètre de la méthode et ce qu’il représente.
• returns : description de ce que la méthode retourne.

Une fois les commentaires XML activés, les outils Swashbuckle peuvent inclure vos commentaires de documentation XML dans la documentation OpenAPI et vous permettent de les afficher dans l’interface utilisateur Swagger.

Annotations de données

Les annotations de données sont traitées de la même façon. Quand vous ajoutez une annotation à votre modèle, Swagger l’inclut dans la documentation de l’API.

Par exemple, si vous ajoutez l’annotation suivante à un contrôleur :

[Produces("application/json")]

Les informations sont ajoutées dans Swagger UI :

Conseils

Il existe plusieurs annotations de données que vous pouvez utiliser pour décrire votre API.

• Identifiez quels content-types gère votre API sur les demandes et les réponses. Les attributs suivants spécifient que l’API ne doit utiliser que le type de contenu application/json dans les deux sens.

  [Produces("application/json")]
  [Consumes("application/json")]
  

• Identifiez les codes de réponse HTTP potentiels qui peuvent être renvoyés au client appelant. L’attribut suivant illustre une API susceptible de retourner une erreur 404 Introuvable.

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  Votre API peut produire un ensemble standard de codes de réponse. Dans ce cas, vous pouvez utiliser l’attribut suivant pour spécifier 200, 400 et 404 conjointement plutôt qu’individuellement. Pour plus d’informations, consultez Utilisation des conventions des API web.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Générez un paramètre operationId pour améliorer considérablement l’expérience de consommation de l’API, notamment la documentation, la génération de code et l’intégration avec d’autres services. Vous pouvez générer automatiquement ce paramètre operationId en incluant la propriété Name dans le filtre de verbe HTTP.

  [HttpGet("{Height}/{Width}", Name="GetPrice")]
  

Continuer