web-dev-qa-db-fra.com

Description des paramètres du swashbuckle

J'utilise les attributs SwaggerResponse pour décorer les actions de mon contrôleur api. Tout cela fonctionne correctement. Toutefois, lorsque je regarde la documentation générée, le champ de description des paramètres est vide.

Existe-t-il une approche basée sur les attributs pour décrire les paramètres d'action (plutôt que les commentaires XML)?

c#swaggerswashbuckle
16
Slicc

Avec le dernier Swashbuckle, ou plutôt au moins la variante Swashbuckle.AspNetCore que j'utilise, le champ Description des paramètres peut désormais être affiché correctement en sortie. 

Il exige que les conditions suivantes soient remplies:

  • Les commentaires XML doivent être activés et configurés avec Swagger
  • Les paramètres doivent être explicitement décorés avec [FromRoute], [FromQuery], [FromBody] ou [FromUri].
  • Idem pour le type de méthode (get/post/put etc.), qui devrait être décoré avec [Http...]
  • Décrivez le paramètre comme d'habitude avec un commentaire <param ...> xml

Un échantillon complet ressemble à ceci:

/// <summary>
/// Short, descriptive title of the operation
/// </summary>
/// <remarks>
/// More elaborate description
/// </remarks>
/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

Ce qui produit la sortie suivante:

 Swagger output with parameter description

23
Juliën

Vous devez confirmer que vous autorisez Swagger à utiliser des commentaires XML.

httpConfig.EnableSwagger(c => {
                if (GetXmlCommentsPath() != null) {
                    c.IncludeXmlComments(GetXmlCommentsPath());
                }
...
...
);

protected static string GetXmlCommentsPath() {
    var path = HostingEnvironment.MapPath("path to your xml doc file");
    return path;
}

Vous devez également vérifier que vous générez une documentation XML pour le projet souhaité. Sous votre projet souhaité Propriétés (Alt + Entrée en haut du projet ou clic droit -> Propriétés) -> Construire -> Vérifier Fichier de documentation XML

4
Alfredo A.

Par souci d’exhaustivité, lors de l’utilisation des dernières versions de Swashbuckle.AspNetCore (2.1.0) et Swashbuckle.SwaggerGen/Ui (6.0.0), activez la génération de fichier de documentation XML dans la construction de votre projet

Ensuite, procédez comme suit pour votre méthode ConfigureServices():

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "My API",
        Description = "API Description"
    });
    options.DescribeAllEnumsAsStrings();

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml");
    if (File.Exists(xmlDocFile))
    {
        var comments = new XPathDocument(xmlDocFile);
        options.OperationFilter<XmlCommentsOperationFilter>(comments);
        options.ModelFilter<XmlCommentsModelFilter>(comments);
    }
});
0
Adriaan de Beer