CODEWITHSUNDEEP
asp.net-web-apiowinswaggerswashbuckle
Marcus
Marcus

Reputation: 8669

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

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?

Upvotes: 17

Views: 17129

Answers (2)

Marcus
Marcus

Reputation: 8669

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

Output XML for the project where model classes are located

  1. 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"

Post-build event to copy the XML file to the same bin folder as the API xml file

  1. 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.

Click models to see model and property comments

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.

Upvotes: 40

Silly John
Silly John

Reputation: 1704

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?

Upvotes: -1

Related Questions