Swagger API not refreshing the documentation

Question

I am using the Swagger API for documenting my REST services. Earlier my controller method didn't have the informative comments, so Swagger API was not showing up the description, but now even after updating the comments like I am not getting the method description in the highlighted area.

    /// <summary>
    /// Gets the consumer scores by retailer id and return id
    /// </summary>
    /// <param name="retailerId"></param>
    /// <param name="returnId"></param>
    /// <returns></returns>

Am I missing anything?

Answer 1

In order for Swashbuckle to read from your XML comments, you will need to enable the XML documentation file for your target project. In addition to that you will need to point Swashbuckle at that file in your startup configuration.

From the Swashbuckle Documentation:

Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked. This will produce a file containing all XML comments at build-time.

At this point, any classes or methods that are NOT annotated with XML comments will trigger a build warning. To supress this, enter the warning code "1591" into the "Supress warnings" field in the properties dialog.*

Configure Swashbuckle to incorporate the XML comments on file into the generated Swagger JSON:

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

     var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

Annotate your actions with summary, remarks and response tags

/// <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(typeof(void), 500)]
public Product GetById(int id)

Rebuild your project to update the XML Comments file and navigate to the Swagger JSON endpoint. Note how the descriptions are mapped onto corresponding Swagger fields.