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?

score 38 · Accepted Answer · answered Sep 20 '16 at 08:20

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.

Generate XML for project where POCOs are located

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"

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.

For me, it's not loading the `
` for properties on my model unless it's a primitive type like `int`, `bool`, `string`, etc. Did you run into this issue? — jtate, Jun 17 '19 at 17:52

score -1 · Answer 2 · answered Sep 19 '16 at 20:43

-1

If you have put the below statement

c.IncludeXmlComments(GetXmlCommentsPath());

Can you check if the xml comment path method returns the path of the xml file where the Project XML Documentation file is placed?

answered Sep 19 '16 at 20:43

Silly John

1,584
2
16
34

The XML file exists and there is no problem with the generated comments which is default (Controller and Method documentation), but this is not what I am asking for - I also want to include the comments from the class definitions of the classes used as method input parameters. I don´t know how else to explain it. – Marcus Sep 19 '16 at 21:03
Better post your request/issue in their Github website - https://github.com/domaindrivendev/Swashbuckle – Silly John Sep 20 '16 at 13:27

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

2 Answers2