Swashbuckle.webapi: XmlComments fail to generate comments when models used from external class library

Created on 26 May 2016 · 3Comments · Source: domaindrivendev/Swashbuckle.WebApi

just got swagger generated and i'm pumped! love this project! but i noticed an issue that i'm hoping to find the answer to but the more i search for it there's no luck, so if anyone has any insight on this i'd love to know what i'm lacking right now.

i'm keeping the models in a business layer and just including them in the controller through a using reference. the main issue is that the summary xmlcomments aren't being recognized in the generated swagger.

so here's the commented code:

commented code

and the generated swagger:

uncommented swagger

this confused me. looking into it i recognized that swashbuckle was included in the api project within the solution, but the business project layer does not have it included (this is my prime suspicion for this issue however adding swashbuckle to business layer is an issue as that would create xml file conflictions) so i went to the models folder of api: models->add->existing item->and navigated to the models from my isbnbusiness project: (sorry for long verticle picture)

structure of solution

once i did so i changed the namespace and set this up within the controller:

using statements

so its not the prettiest (possibly a buggy patch waiting to burst) solution but when i did this the swagger generated this:

commented swagger

so a fix? maybe. but i'd really rather only be using isbnbusiness' and not the api's models

how can i fix this so that swashbuckle will recognize the comments of the models of the business layer project and generate the

comments i need in swagger?

Source

kmmacgill

Most helpful comment

There is a very simple solution this.
You need to generate the xmldocumentation for the project where the models reside
in project properties/Build
windows_10

Then in swagger.config create a static string that returns the xml file location

protected static string GetXmlCommentsForDTO()
        {
            return System.String.Format(@"{0}\bin\MyProject.DTO.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }

And then in the swaggerconfiguration c.IncludeXmlComments(GetXmlCommentsForDTO()); and you are all set :)

VisualBean on 14 Jun 2016

👍2

All 3 comments

There is a very simple solution this.
You need to generate the xmldocumentation for the project where the models reside
in project properties/Build
windows_10

Then in swagger.config create a static string that returns the xml file location

protected static string GetXmlCommentsForDTO()
        {
            return System.String.Format(@"{0}\bin\MyProject.DTO.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }

And then in the swaggerconfiguration c.IncludeXmlComments(GetXmlCommentsForDTO()); and you are all set :)

VisualBean on 14 Jun 2016

👍2

I think this can be closed

VisualBean on 25 Jun 2016

👍1

@domaindrivendev thank you, I just want to add that we can get comments from multiple files in swashbuckle

c.IncludeXmlComments(GetXmlCommentsPath());
c.IncludeXmlComments(GetXmlCommentsPathCommon());'

private static string GetXmlCommentsPath()
{
   return AppDomain.CurrentDomain.BaseDirectory + @"bin\ReportingAPI.xml";
}

private static string GetXmlCommentsPathCommon()
{
    return AppDomain.CurrentDomain.BaseDirectory + @"bin\ReportingAPI.Common.xml";
}