Add IncludeXmlCommentsForAssembly convience overload (#2909)

Add IncludeXmlCommentsForAssembly convenience overload.

Author: leotsarev

README.md

@@ -540,7 +540,8 @@ To enhance the generated docs with human-friendly descriptions, you can annotate
          );
 
          var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
-         c.IncludeXmlComments(filePath);
+         c.IncludeXmlComments(Assembly.GetExecutingAssembly());
+         // or c.IncludeXmlComments(typeof(MyController).Assembly));
     }
     ```
 

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

@@ -1,10 +1,12 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
+using System.Reflection;
 using System.Xml.XPath;
-using Microsoft.OpenApi.Models;
+using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
-using Microsoft.AspNetCore.Authentication;
 
 namespace Microsoft.Extensions.DependencyInjection
 {
@@ -556,6 +558,26 @@ public static void IncludeXmlComments(
             swaggerGenOptions.IncludeXmlComments(() => new XPathDocument(filePath), includeControllerXmlComments);
         }
 
+        /// <summary>
+        /// Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML comments
+        /// from specific Assembly
+        /// </summary>
+        /// <param name="swaggerGenOptions"></param>
+        /// <param name="assembly">Assembly that contains XML Comments</param>
+        /// <param name="includeControllerXmlComments">
+        /// Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions.
+        /// Don't set this flag if you're customizing the default tag for operations via TagActionsBy.
+        /// </param>
+        public static void IncludeXmlComments(
+            this SwaggerGenOptions swaggerGenOptions,
+            Assembly assembly,
+            bool includeControllerXmlComments = false)
+        {
+            swaggerGenOptions.IncludeXmlComments(
+                Path.Combine(AppContext.BaseDirectory, $"{assembly.GetName().Name}.xml"),
+                includeControllerXmlComments);
+        }
+
         /// <summary>
         /// Generate polymorphic schemas (i.e. "oneOf") based on discovered subtypes.
         /// Deprecated: Use the \"UseOneOfForPolymorphism\" and \"UseAllOfForInheritance\" settings instead

test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs

@@ -1,15 +1,14 @@
-using System.Xml.XPath;
-using System.Collections.Generic;
-using System.Reflection;
+using System.Collections.Generic;
 using System.IO;
+using System.Reflection;
+using System.Xml.XPath;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.FileProviders;
 using Microsoft.OpenApi.Models;
 using Xunit;
-using Swashbuckle.AspNetCore.TestSupport;
 
 namespace Swashbuckle.AspNetCore.SwaggerGen.Test
 {
@@ -144,7 +143,7 @@ public void Ensure_IncludeXmlComments_Adds_Filter_To_Options()
             services.AddSwaggerGen(c =>
             {
                 c.IncludeXmlComments(
-                    $"{typeof(FakeControllerWithXmlComments).Assembly.GetName().Name}.xml",
+                    typeof(FakeControllerWithXmlComments).Assembly,
                     includeControllerXmlComments: true);
             });
 

test/WebSites/Basic/Startup.cs

@@ -1,14 +1,14 @@
 using System;
 using System.Globalization;
-using System.IO;
+using System.Reflection;
+using Basic.Swagger;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Localization;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.OpenApi.Models;
-using Microsoft.AspNetCore.Localization;
-using Basic.Swagger;
 
 namespace Basic
 {
@@ -52,7 +52,7 @@ public void ConfigureServices(IServiceCollection services)
                 c.SelectDiscriminatorNameUsing((baseType) => "TypeName");
                 c.SelectDiscriminatorValueUsing((subType) => subType.Name);
 
-                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Basic.xml"));
+                c.IncludeXmlComments(Assembly.GetExecutingAssembly());
 
                 c.EnableAnnotations();
             });

test/WebSites/GenericControllers/Startup.cs

@@ -1,11 +1,10 @@
-using System.IO;
+using System.Reflection;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.OpenApi.Models;
-using GenericControllers.Swagger;
 
 namespace GenericControllers
 {
@@ -27,8 +26,7 @@ public void ConfigureServices(IServiceCollection services)
             {
                 c.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "1" });
 
-                var xmlCommentsPath = Path.Combine(System.AppContext.BaseDirectory, "GenericControllers.xml");
-                c.IncludeXmlComments(xmlCommentsPath);
+                c.IncludeXmlComments(Assembly.GetExecutingAssembly());
 
                 //c.OperationFilter<ApplySummariesOperationFilter>();
             });