web-dev-qa-db-fra.com

Comment ajouter une description de méthode dans l'interface utilisateur Swagger dans une application API Web

J'utilise Swagger comme cadre d'outils d'API et tout fonctionne à merveille jusqu'à présent. Je viens de tomber sur cette page https://petstore.swagger.io/

et vu comment chaque méthode a une description. Par exemple, 

POST: pet/ est décrit par add a new Pet to the store. Je pensais que l'ajout de quelque chose comme [Description("Description text")] devrait le faire, mais ce n'est pas le cas. Comment puis-je atteindre cet objectif?

c#asp.net-core-webapiswagger-uirestful-urlswashbuckle
4
Lost

Ceci est bien documenté dans le projet: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

Inclure des descriptions à partir de commentaires XML

Pour améliorer les documents générés avec des descriptions conviviales, vous pouvez annoter les actions du contrôleur et les modèles avec Commentaires xml et configurer Swashbuckle pour incorporer ces commentaires dans le JSON Swagger généré:

1 - Ouvrez la boîte de dialogue Propriétés de votre projet, cliquez sur l'onglet "Générer" et assurez-vous que le "fichier de documentation XML" est coché. Cela produira un fichier contenant tous les commentaires XML au moment de la construction.

A ce stade, toutes les classes ou méthodes qui ne sont PAS annotées avec des commentaires XML déclenchent un avertissement de construction. Pour le supprimer, entrez le code d'avertissement "1591" dans le champ "Supprimer les avertissements" de la boîte de dialogue des propriétés.

2 - Configurez Swashbuckle pour incorporer les commentaires XML au fichier dans le JSON Swagger généré:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

3 - Annotez vos actions avec des tags de résumé, remarques et réponses:

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

4 - Vous pouvez également annoter des types avec des balises summary et example:

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

    /// <summary>
    /// Quantity left in stock
    /// </summary>
    /// <example>10</example>
    public int AvailableStock { get; set; }
}

5 - Reconstruisez votre projet pour mettre à jour le fichier de commentaires XML et accédez au point de terminaison Swagger JSON. Notez comment les descriptions sont mappées sur les champs Swagger correspondants.

REMARQUE: Vous pouvez également fournir des descriptions de schéma Swagger en annotant vos modèles d'API et leurs propriétés avec des balises récapitulatives. Si vous avez plusieurs fichiers de commentaires XML (par exemple, des bibliothèques séparées pour les contrôleurs et les modèles), vous pouvez appeler la méthode IncludeXmlComments plusieurs fois et ils seront tous fusionnés dans le JSON Swagger généré.

En suivant attentivement les instructions, vous devriez obtenir quelque chose qui ressemble à:
https://swashbucklenetcore.azurewebsites.net/swagger/

11
Helder Sepulveda

Vous pouvez utiliser le commentaire pour la documentation (3 barres obliques au lieu de la norme 2) comme:

/// <summary>
/// This is method summary I want displayed
/// </summary>
/// <param name="guid">guid as parameter</param>
/// <param name="page_number">Page number - defaults to 0</param>
/// <returns>List of objects returned</returns>
0
Caldazar