XML comments from dependent Assemblies

[Zaphod99]

I may be missing something obvious here but I can't seem to figure out how to include XML comment documentation from more than one assembly. I have a web project that produces file a.xml in the app_data directory. I also have a DTO project that contains the objects the web project returns. It produces an xml file, b.xml. I have been able to include one file or the other, and Swashbuckle picks up either set of comments. However, I don't know how to ask it to look at both files at once. Is that supported?

string path = AppDomain.CurrentDomain.GetData("DataDirectory").ToString() + "\a.xml";
SwaggerSpecConfig.Customize(
c => c.IncludeXmlComments(path));

Great project, btw!

[domaindrivendev]

Hey there

Unfortunately, this is a use-case that I hadn't considered until yourself (and others) pointed it out. I've always thought of routes/controllers and DTO's as being very closely related (i.e. they "are" the API contract) and have never wanted to separate them into different libraries. Domain logic on the other hand would live in a separate project with mapping in place to convert between DTO's and Domain objects.

But I can see now there are many reasons why people might want to do things differently and so believe that Swashbuckle should support this feature. Actually, it's probably not a significant change but the backlog is growing and I'll need to figure out where it sits on the list of priorities.

In the meantime though, I have a workaround you could try but I have a sneaking suspicion it may result in some unwanted repercussions.

If you look at the code, you'll see that IncludeXmlComments is really just a convenience method that wires up two "filters' - ApplyActionXmlComments and ApplyTypeXmlComments. You could conceivably just wire these up yourself providing a different file path for each.

There is a gotcha though, this approach will cause the static config instance to hold onto to a ref for each of these filters which in turn will hold a ref to an XmlDocument. This may cause some memory issues but maybe you can do some trickery to work around it. Might be worth a try ...

[Zaphod99]

Thanks for the response!

I wrote this as a workaround... seems to work. Including in case it helps someone out. Unless you see an issue I may just use this.

///

    /// Contains initialization settings for Swashbuckle. Sets up the documentation that will be displayed in Swagger by combining the
    /// various xml comment files.
    /// Place a comma delimited string with the XML comment filenames that exist in App_Data that will be used for the swagger documentation
    /// in the web config app settings.  Setting name is XMLCommentFileNames.
    /// </summary>

    public static void Register()
    {
        Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);
        XElement xml = null;
        XElement dependentXml = null;
        //build one large xml comments file
        foreach (string fileName in WebConfigurationManager.AppSettings["XMLCommentFileNames"].Split(','))
        {
            string qualifiedFileName = AppDomain.CurrentDomain.GetData("DataDirectory").ToString() + "\\" + fileName;
            if (xml == null)
            {
                xml = XElement.Load(qualifiedFileName);
            }
            else
            {
                dependentXml = XElement.Load(qualifiedFileName);
                foreach (XElement ele in dependentXml.Descendants())
                {
                    xml.Add(ele);
                }
            }
        }

        //save comments file, point swagger at it.
        string swaggerFile = AppDomain.CurrentDomain.GetData("DataDirectory").ToString() +
                         "\\CombinedDocumentation.xml";
        if (xml != null)
        {
            xml.Save(swaggerFile);
            SwaggerSpecConfig.Customize(
              c => c.IncludeXmlComments(swaggerFile));
        }
    }

[viku85]

This issue still haunts in 2018.
My solution for the same.

Function to get a of XML doc:
private static string GetXmlCommentPath(string assemblyName) => Path.Combine(AppContext.BaseDirectory, assemblyName + ".xml");

Register XML files with help of C# nameof without using any reflection.
options.IncludeXmlComments(GetXmlCommentPath($"{nameof(MyProject)}.{nameof(Db)}")); options.IncludeXmlComments(GetXmlCommentPath(nameof(SomeOtherNamespace))); options.IncludeXmlComments(GetXmlCommentPath($"{nameof(MyProject)}.{nameof(Core)}"));

[akalcik]

It can be a option to add all xml files from bin directory.

List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory,"*.xml",SearchOption.TopDirectoryOnly).ToList();
xmlFiles.ForEach(xmlFile => swaggerGenOptions.IncludeXmlComments(xmlFile));

[Rozzemak]

It can be a option to add all xml files from bin directory.

List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory,"*.xml",SearchOption.TopDirectoryOnly).ToList();
xmlFiles.ForEach(xmlFile => swaggerGenOptions.IncludeXmlComments(xmlFile));

Elegant solution. Highly configurable and simple.