CODEWITHSUNDEEP
c#swaggerswashbuckle
Slicc
Slicc

Reputation: 3435

Swashbuckle parameter descriptions

I'm using SwaggerResponse attributes to decorate my api controller actions, this all works fine, however when I look at the generated documentation the description field for parameters is empty.

Is a there an attribute based approach to describe action parameters (rather than XML comments)?

Upvotes: 33

Views: 76443

Answers (4)

Songlet Li
Songlet Li

Reputation: 1

Use Annotations. Package is Swashbuckle.AspNetCore.Annotations. https://github.com/domaindrivendev/Swashbuckle.AspNetCore#swashbuckleaspnetcoreannotations

Like this. description for parameters

Upvotes: 0

Juliën
Juliën

Reputation: 9532

With the latest Swashbuckle, or better said at least the Swashbuckle.AspNetCore variant which I'm using, the Description field for parameters can now be displayed correctly as output.

It does require the following conditions to be met:

  • XML comments must be enabled and configured with Swagger
  • Parameters should be explicitly decorated with either [FromRoute], [FromQuery], [FromBody] etc.
  • The same for the method type (get/post/put etc.), which should be decorated with [Http...]
  • Describe the parameter as usual with a <param ...> xml comment

A full sample looks like this:

/// <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);
}

Which produces the following output:

Swagger output with parameter description

Upvotes: 54

Adriaan de Beer
Adriaan de Beer

Reputation: 1286

For completeness sake, when using latest version of Swashbuckle.AspNetCore (2.1.0) and Swashbuckle.SwaggerGen/Ui (6.0.0), enable Xml documentation file generation in your project's Build

Then the following to your ConfigureServices() method:

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);
    }
});

Upvotes: 0

Alfredo A.
Alfredo A.

Reputation: 1777

You should confirm you are allowing Swagger to use XML comments

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;
}

You should also check you are generating XML doc for your desired project. Under your desired project Properties (Alt + Enter on top of the project or Right Click -> Properties) -> Build -> Check XML documentation file

Upvotes: 9

Related Questions