How to include class and property descriptions in Swashbuckle generated Swagger docs for WebApi 2 with OWIN?

Question

Before you think of it, this is not the same.

I think this should be pretty much self explanatory. I would like to include class descriptions in the Swagger docs. My Swagger config looks like this:

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());

}).EnableSwaggerUi(c => { });

And MyAwesomeController looks like this:

/// <summary>
/// Controller description (is included by Swashbuckle)
/// </summary>
public class MyAwesomeController : ApiController
{
    /// <summary>
    /// Method description (is included by Swashbuckle)
    /// </summary>
    public IHttpActionResult Get()
    {
        return Ok("hello... from the other side");
    }

    public IHttpActionResult Post([FromBody]MyAwesomeModel model)
    {
        return Ok("hello... from the other side");
    }
}

And my MyAwesomeModel looks like this:

/// <summary>
/// **I would like this to be included in the Swagger description of the parameter**
/// </summary>
public class MyAwesomeModel
{
    /// <summary>
    /// **I would like this to be included in the Swagger description of the parameter**
    /// </summary>
    public string MyProperty { get; set; }
}

Is this possible without hiring Sr. Skeet?

Answer 1

Hm... so maybe if someone else runs into this.

Basically I found one way this can be done and I realized why it was not done by default. Not sure if it is the best approach but here it goes.

In my solution, the POCOs are located in a project separate to the actual API and thus, the comment description of MyAwesomeModel was not included because no XML nodes were generated for the classes and properties. So, in my separate project where the POCOs were located I modified properties to generate an XML.

1. Generate XML for project where POCOs are located

2. Make sure the XML is copied to whatever path you would like Swashbuckle to look for it. I used Post-build event command line in project properties;

copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"

3. Modify SwaggerConfig to include this XML as well

I.e.

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());
    c.IncludeXmlComments(GetXmlCommentsPathForModels());

}).EnableSwaggerUi(c => { });

Now, on the Swagger page, if I switch from Model Schema to Model I can now read the entire model and property descriptions.

Naturally, there is no demand to copy the XML file, one may just point to the correct location in step #3 GetXmlCommentsPathForModels()); but this was my option.