Swashbuckle.webapi: <summary> xml annotation not working for properties in nested objects

[maniacally]

Assuming we have a model called Group that looks like this:

    public class Group{
      ///<summary>
      /// Some description of GroupName
      ///</summary>
      public string GroupName{get;set;}
      public List<Person> People {get;set;} 
    }

and a Person class that looks like this:

    public class Person{
      ///<summary>
      /// Some description of Name
      ///</summary>
      public string Name{get;set;}
    }

If we then use the ResponeType attribute for an API action and set it to typeof(Group) the resulting documentation for the action will only show the descriptions in the

element for the top level properties (GroupName, for ex). The description in the

element of the nested Person class (for Name) is not reflected in the generated documentation.

[domaindrivendev]

Hi there

I'm unable to repro this issue. I created the following controller

public class GroupsController : ApiController
{
    [ResponseType(typeof(Group))]
    public HttpResponseMessage GetById(int id)
    {
        throw new NotImplementedException();
    }
}

And copy n pasted your Group and Person classes above. Here's the resulting swagger-ui ...

[maniacally]

I apologise. I typed this up without my code in front of me. The problem occurs when the Action accepts this type of model as input, not when it returns this type of model as ResponseType. In the "model schema" portional of the UI, the xml summaries for nested parameters do not appear. Happy to create a separate issue if you prefer. Again, sorry for the bad writeup.

[SuTV]

@domaindrivendev : What happen if Group and Person class are not the same project with GroupsController's project?
In my situation, I have a API project and Data project and swagger did not display Data property description.

[SuTV]

I solved the problem above by using IModelFilter: instead of using xml comment, I use Attribute to set description. Is there any better solution for that?

[domaindrivendev]

The real problem here is that the current Swashbuckle only allows one XML file to be used. Subsequent calls to IncludeXmlComments will just override the file path provided by the previous ones.

NOTE: This will be fixed in the next release of Swashbuckle (v4.1)

[SuTV]

very good news :+1:

[radduri]

I am using 6.0 but still facing the same issue. Any help?

[Magic73]

Me too. With the lastest version...

I have to use multiple XML docs, because the models are in an external library (which creates its own xml doc)

[luboshl]

I am using version 5.6.0 and multiple XML docs works for me:

var dir = new DirectoryInfo(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "bin"));
foreach (var fi in dir.EnumerateFiles("*.xml"))
{
    c.IncludeXmlComments(fi.FullName);
}

[raffaeu]

@luboshl that worked for me, Swagger on asp.net core 2.1

[andyliutyme]

3 years later, @luboshl 's solution still works 👍