From d66ae91131340b2d45a722457cc60dcd6069403e Mon Sep 17 00:00:00 2001 From: Leonid Tsarev Date: Sat, 18 May 2024 14:32:46 +0300 Subject: [PATCH 1/2] Add IncludeXmlCommentsForAssembly convience overload --- README.md | 3 ++- .../SwaggerGenOptionsExtensions.cs | 26 +++++++++++++++++-- .../XmlCommentsDocumentFilterTests.cs | 9 +++---- test/WebSites/Basic/Startup.cs | 8 +++--- test/WebSites/GenericControllers/Startup.cs | 6 ++--- 5 files changed, 36 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5a5ed3f42f..0e7dc0a9a4 100644 --- a/README.md +++ b/README.md @@ -539,7 +539,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)); } ``` diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs index 92aa466297..74af8a0d67 100644 --- a/src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs +++ b/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); } + /// + /// Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML comments + /// from specific Assembly + /// + /// + /// Assembly that contains XML Comments + /// + /// 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. + /// + public static void IncludeXmlComments( + this SwaggerGenOptions swaggerGenOptions, + Assembly assembly, + bool includeControllerXmlComments = false) + { + swaggerGenOptions.IncludeXmlComments( + Path.Combine(AppContext.BaseDirectory, $"{assembly.GetName().Name}.xml"), + includeControllerXmlComments); + } + /// /// Generate polymorphic schemas (i.e. "oneOf") based on discovered subtypes. /// Deprecated: Use the \"UseOneOfForPolymorphism\" and \"UseAllOfForInheritance\" settings instead diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs index c92fab0425..5fe5a2421b 100644 --- a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs +++ b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs @@ -1,7 +1,7 @@ -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; @@ -9,7 +9,6 @@ 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); }); diff --git a/test/WebSites/Basic/Startup.cs b/test/WebSites/Basic/Startup.cs index a4e97a9364..f0d44a170d 100644 --- a/test/WebSites/Basic/Startup.cs +++ b/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(); }); diff --git a/test/WebSites/GenericControllers/Startup.cs b/test/WebSites/GenericControllers/Startup.cs index a217882dc9..1c931a0ba3 100644 --- a/test/WebSites/GenericControllers/Startup.cs +++ b/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(); }); From a5a7a8ff4aa5eb5f9c995757c5665c880e5a35d4 Mon Sep 17 00:00:00 2001 From: Leonid Tsarev Date: Sun, 19 May 2024 11:04:18 +0300 Subject: [PATCH 2/2] Update README.md Co-authored-by: Martin Costello --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e7dc0a9a4..ccca0c65ce 100644 --- a/README.md +++ b/README.md @@ -540,7 +540,7 @@ To enhance the generated docs with human-friendly descriptions, you can annotate var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"); c.IncludeXmlComments(Assembly.GetExecutingAssembly()); - // or c.IncludeXmlComments(typeof(MyController).Assembly)); + // or c.IncludeXmlComments(typeof(MyController).Assembly)); } ```