How to include summaries from the framework classes in the Swagger documentation?

Question

I know how to use the XML documentation files generated for my own projects, so that Swashbuckle feeds them to the Swagger documentation, but is there a way to do the same for the standard framework classes? For example, if my API references a system framework type, how do I get the summary and documentation defined for this type (and visible via IntelliSense) included in the Swagger documentation?

Answer 1

The same way you include your own project's XML documentation in your Swagger documentation, you can also include XML documentation of the .NET Framework or any other library.

You need to find the XML documentation file for the library (it usually resides in the same folder as the DLL file, with the same name but with a .xml extension) and include it in your Swagger configuration.

Here's how you can do it for .NET Core or .NET 5+,First, ensure that the XML documentation file for the framework DLL is present. For .NET Core or .NET 5+, these files are usually located in the NuGet package store (%userprofile%.nuget\packages on Windows, ~/.nuget/packages on Unix-based systems). They are located in the same directory as the DLL files, with the same name but with an .xml extension.

Once you have located the XML file, you can add it to your Swagger configuration in your Startup.cs,

public void ConfigureServices(IServiceCollection services)
{

    services.AddSwaggerGen(c =>
    {
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
        
        var frameworkXmlPath = @"<path-to-framework-xml-file>";
        c.IncludeXmlComments(frameworkXmlPath);
    });
}

please replace with the actual path to the XML documentation file for the framework DLL.

if you're using Docker or other containerisation/deployment techniques, make sure that the XML files are included in your deployment package.

PS: not all types in the .NET framework are documented, and even when they are, the documentation may not be as comprehensive as what you might write for your own types.