How to include XML comments files in Swagger in ASP.NET Core

Enable "XML documentation file" checkbox for each project you depend on to generate their files on build. It could be done at project's properties Build tab.

To include all XML files on deploy, add this target to the published project's csproj file:

<Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
        <DocFile Include="bin\*\*\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" 
          DestinationFolder="$(PublishDir)" 
          SkipUnchangedFiles="false" />
</Target>

This will copy all XML files from bin folder and nested subfolders (like bin\Release\netcoreapp1.1\) to publish dir. Of course you can customize that target.


For .Net Core 2 upto 3.1 versions it's slightly different, for those who come across it using a newer version you would create your private void ConfigureSwagger(IServiceCollection services) constructor, add the reference to swagger services.AddSwaggerGen(c => { c.SwaggerDoc(/*populate with your info */); then define a new parameter which will be the path for your swagger XML documentation: var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml"); c.IncludeXmlComments(filePath);.

It should look something like this:

private void ConfigureSwagger(IServiceCollection services)
    {
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info
            {
                Version = "v1",
                Title = "YourApiName",
                Description = "Your Api Description.",
                TermsOfService = "None",
                Contact = new Contact
                    {Name = "Contact Title", Email = "[email protected]", Url = ""}
            });
            var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml");
            c.IncludeXmlComments(filePath);
        });
    }

For this to work, you need to ensure that the build's Output has the documentation file checked (see red arrow) and the path set appropriately. I've noticed that you can strip the pre-filled path and just use bin\YourApiName.xml, just like below:

Image showing how to enable XML documentation in Visual Studio 2017 IDE

Update: If these changes aren't working as expected, please check the configuration. In the example, the config is set to Debug. If you're running from a different environment (env) you may need to check whether these setting apply to that env.

Update 2: Since the release of OpenAPI I thought I'd update my example (below) to show a more accurate reference to this specification which should follow something similar to:

services.AddSwaggerGen(o =>
            {
                o.SwaggerDoc("v1",
                    new OpenApiInfo
                    {
                        Title = "Your API Name",
                        Description = "Your API Description",
                        Version = "v1",
                        TermsOfService = null, 
                        Contact = new OpenApiContact 
                        {
                            // Check for optional parameters
                        },
                        License = new OpenApiLicense 
                        {
                            // Optional Example
                            // Name = "Proprietary",
                            // Url = new Uri("https://someURLToLicenseInfo.com")
                        }
                    });
            });