Use property XML comments as parameter descriptions in Swagger

Question

I created a Web API using ASP.NET Core and used swagger to create documentation. I use the XML comments on my API endpoints to provide additional information in the documentation. The swagger configuration is:

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

            // Set the comments path for the Swagger JSON and UI.
            var basePath = AppContext.BaseDirectory;
            var xmlPath = Path.Combine(basePath, "MyAPI.xml");
            c.IncludeXmlComments(xmlPath);
        });

One of my API endpoints and its XML comments are:

    /// <summary>
    /// Find an existing appointment using the visitor information: First name, last name, email, phone.
    /// </summary>
    /// <url>http://apiurl/api/appointments/appointmentsByVisitor</url>
    /// <param name="criteria">consists of one or more of:  Firstname, lastname, email, phone</param>
    /// <returns>Existing appointment data in an Appointment object or a business error.</returns>
    /// <response code="200">Returns the existing appointment event.</response>
    /// <response code="400">Returns if no parameters are specified.</response>            
    /// <response code="204">Returns if there's no matching appointment.</response>
    /// <response code="500">Returns if there's an unhandled exception.</response>
    [Authorize]
    [HttpGet("appointmentsByVisitor")]
    [ProducesResponseType(typeof(Appointment), 200)]
    [ProducesResponseType(typeof(BusinessError), 404)]
    public IActionResult AppointmentsByVisitor([FromQuery] VisitorSearchCriteria criteria) {}

VisitorSearchCriteria is a separate class which is a wrapper for the parameters expected by the API endpoint.

public class VisitorSearchCriteria
{
    /// <summary>
    /// Visitor first name.
    /// </summary>
    public string FirstName { get; set; }

    /// <summary>
    /// Visitor last name.
    /// </summary>
    public string LastName { get; set; }

    // several other properties....
}

The swagger documentation for this API endpoint shows all the properties of VisitorSearchCriteria as parameters, but it doesn't pick the XML comments. See the screenshot below.

As you can see, the descriptions of the parameters are missing. How do I tell swagger to use the XML comments from that external class to create parameter descriptions?

Answer 1

If you have a model class defined in a different project then you need to go to Properties of this project and under the Build/Output check the "XML documentation file:" option. Then you need to update the swagger config file adding.

c.IncludeXmlComments($@"{System.AppDomain.CurrentDomain.BaseDirectory}\YourProjectName.xml");

The YourProjectName.xml should contain the description of your model class fields of course in the XML format.

If you would like to import comments from the different project you need to do the same thing as above, adding

c.IncludeXmlComments($@"{System.AppDomain.CurrentDomain.BaseDirectory}\YourProjectName2.xml");

to the swagger config file.

Keep in mind there can be an XML file generated per project and you are able to add the comments from all of those files to your swagger UI. When you run your Swagger UI the comments should appear in the Model section.

Answer 2

http://wmpratt.com/swagger-and-asp-net-web-api-part-1/

First, enable XML documentation file creation during build. In Solution Explorer right-click on the Web API project and click Properties. Click the Build tab and navigate to Output. Make sure XML documentation file is checked. You can leave the default file path. In my case its bin\SwaggerDemoApi.XML