Exercice – Personnalisation et extension de la documentation OpenAPI avec des annotations et des commentaires XML - Training

12 minutes

Dans cet exercice, vous enrichissez la documentation qu’un développeur voit sur votre API en ajoutant des annotations et des commentaires à votre code. Voyons d’abord ce que Swagger UI nous propose par défaut.

Pour examiner la définition OpenAPI du point de terminaison de l’API dans Swagger UI, accédez à http://localhost:5000/swagger dans votre navigateur. Vous devriez voir une sortie similaire à ce qui suit quand vous sélectionnez la méthode Get.

Swagger UI nous donne des informations utiles sur l’API. Il montre les méthodes que vous pouvez appeler (notre exemple simple n’en compte qu’une seule, appelée PriceFrame). Vous voyez que c’est une opération HTTP Get qui prend deux paramètres obligatoires, Height et Width. Pour voir l’appel d’API en action, vous pouvez sélectionner Essayer, affecter des valeurs à Height et Width, puis sélectionner Exécuter.

Les utilisateurs de votre API ne disposent toujours pas d’informations suffisantes pour connaître les limitations de la méthode PriceFrame. Nous allons les aider en leur donnant des informations plus détaillées par le biais de commentaires XML.

Ajouter des commentaires XML à l’API

Revenez à l’instance de Visual Studio Code que vous avez utilisée pour le dernier exercice.
Si l’API web est toujours en cours d’exécution dans le dernier exercice, appuyez sur Ctrl+c sur Windows ou Cmd+c sur Mac pour l’arrêter.
Pour activer la documentation XML dans votre projet, mettez à jour le fichier projet PrintFramerAPI.csproj, ajoutez l’étiquette GenerateDocumentationFile au <PropertyGroup> existant et définissez-la sur true.
```
<PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
```
Dans Startup.cs, ajoutez les instructions using suivantes.
```
using System.Reflection;
using System.IO;
```

Dans Startup.cs, pour indiquer à Swashbuckle d’utiliser la documentation XML, mettez à jour l’appel à AddSwaggerGen() dans ConfigureServices.

 public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();

     // Register the Swagger generator, defining 1 or more Swagger documents
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo
         {
             Version = "v1",
             Title = "PrintFramer API",
             Description = "Calculates the cost of a picture frame based on its dimensions.",
             TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"),
             Contact = new OpenApiContact
             {
                 Name = "Your name",
                 Email = string.Empty,
                 Url = new Uri("https://zcusa.951200.xyz/training")
             }
         });

         // Set the comments path for the Swagger JSON and UI.
         var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
         var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
         c.IncludeXmlComments(xmlPath);
     });
 }

Dans le code précédent, le nom du fichier XML contenant les commentaires XML à charger est déterminé par réflexion.

Dans le dossier Controllers, ouvrez PriceFrameController.cs. Ajoutez le bloc de commentaires XML suivant au-dessus de l’attribut HttpGet de la méthode GetPrice. Quand vous ajoutez des commentaires précédés de trois barres obliques à une action, Swagger UI ajoute la description à l’en-tête de la section.

 /// <summary>
 /// Returns the price of a frame based on its dimensions.
 /// </summary>
 /// <param name="Height">The height of the frame.</param>
 /// <param name="Width">The width of the frame.</param>
 /// <returns>The price, in dollars, of the picture frame.</returns>
 /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks>
 [HttpGet("{Height}/{Width}")]
 public string GetPrice(string Height, string Width)
 {
     string result;
     result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
     return $"The cost of a {Height}x{Width} frame is ${result}";
 }

Pour enregistrer toutes les modifications et vous assurer qu’elles sont générées localement, exécutez la commande suivante dans la fenêtre de terminal Visual Studio Code.
```
dotnet build
```
Pour voir vos modifications, exécutez l’application ASP.NET localement en entrant la commande suivante dans la fenêtre de terminal Visual Studio Code :
```
dotnet run
```
Réexaminez Swagger UI à l’emplacement http://localhost:5000/swagger, puis observez les informations ajoutées à la documentation OpenAPI, fournies par vos commentaires XML.

Ajouter des annotations de données à votre API

Pour permettre à Swagger d’améliorer la documentation OpenAPI, vous allez utiliser des attributs de l’espace de noms Microsoft.AspNetCore.Mvc.

Si l’API web est toujours en cours d’exécution dans le dernier exercice, appuyez sur Ctrl+c sur Windows ou Cmd+c sur Mac pour l’arrêter.
Pour montrer que votre API GetPrice prend en charge une réponse de type de contenu pour text/plain, ajoutez un attribut [Produces("text/plain")] au-dessus de la définition GetPrice dans le contrôleur de l’API, PriceFrameController.cs.
```
[HttpGet("{Height}/{Width}")]
[Produces("text/plain")]
```
La liste déroulante Response Content Type (Type de contenu de la réponse) sélectionne ce type de contenu comme valeur par défaut pour les actions GET du contrôleur.

Ajouter des annotations Swashbuckle à votre API

Jusqu’ici, votre API retourne le code d’état 200 quand elle peut calculer un prix pour les dimensions fournies pour le cadre. Dans la description de la méthode GetPrice, notez le cas où un prix ne peut pas être calculé.

Les annotations de données et commentaires XML suivants sont un moyen plus solide d’indiquer aux développeurs les types de réponses et les codes d’erreur. Swashbuckle et les outils Swagger utilisent ces valeurs pour générer clairement une description OpenAPI des codes de réponse HTTP attendus.

Mettez également à jour le constructeur de filtre de verbe HTTP de façon à inclure la propriété Name et incluez la valeur operationId OpenAPI.

Ajoutez l’instruction using suivante au fichier PriceFrameController.cs.
```
using Microsoft.AspNetCore.Http;
```

Dans PriceFrameController.cs, remplacez GetPrice par le code et le commentaire suivants.

/// <summary>
/// Returns the price of a frame based on its dimensions.
/// </summary>
/// <param name="Height">The height of the frame.</param>
/// <param name="Width">The width of the frame.</param>
/// <returns>The price, in dollars, of the picture frame.</returns>
/// <remarks>
/// Sample request:
///
///     Get /api/priceframe/5/10
///
/// </remarks>
/// <response code="200">Returns the cost of the frame in dollars.</response>
/// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response>
[HttpGet("{Height}/{Width}", Name=nameof(GetPrice))]
[Produces("text/plain")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> GetPrice(string Height, string Width)
{
    string result;
    result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
    if (result == "not valid")
    {
        return BadRequest(result);
    }
    else
    {
        return Ok($"The cost of a {Height}x{Width} frame is ${result}");
    }
}

Cette mise à jour du code apporte les modifications suivantes :

La méthode utilise les méthodes BadRequest() et Ok() pour créer respectivement un état BadRequest (400) et un état Ok. Le résultat de la chaîne est passé à la réponse.
Les commentaires XML décrivent chaque code d’état que cette méthode peut retourner.
L’attribut HttpGet inclut une propriété Name pour émettre le paramètre operationId OpenAPI.
Les attributs ProducesResponseType répertorient les différentes réponses que l’action peut retourner. Ces attributs sont combinés avec des commentaires XML comme décrit précédemment, pour inclure des descriptions compréhensibles par les humains avec chaque réponse dans le Swagger généré.

Régénérez l’API web avec la commande suivante :
```
dotnet build
```
Exécutez l’application ASP.NET avec la commande suivante :
```
dotnet run
```
Réexaminez à nouveau Swagger UI à l’emplacement http://localhost:5000/swagger et observez les informations ajoutées fournies par ces annotations. Le Swagger UI pour votre API apparaît dans l’image suivante.

Dans cet exercice, vous avez enrichi les informations qu’un développeur reçoit sur votre API, qui la rendent beaucoup plus facile à utiliser.

Continuer

Exercice – Personnalisation et extension de la documentation OpenAPI avec des annotations et des commentaires XML

Ajouter des commentaires XML à l’API

Ajouter des annotations de données à votre API

Ajouter des annotations Swashbuckle à votre API

Commentaires