diff --git a/CHANGELOG.md b/CHANGELOG.md index edbcfe4..8a5ec97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ These are the changes to each version that has been released on the [nuget](https://www.nuget.org/packages/Unchase.Swashbuckle.AspNetCore.Extensions/). +## v2.4.1 `2020-10-13` + +- [x] Add `params Type[]` parameters to `IncludeXmlCommentsWithRemarks` option to exclude remarks for concrete types + ## v2.4.0 `2020-10-11` - [x] Add `IncludeXmlCommentsWithRemarks` option to add xml comments from summary and remarks into the swagger documentation diff --git a/README.md b/README.md index 4be2814..14567cf 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,13 @@ public void ConfigureServices(IServiceCollection services) // use it if you want to hide Paths and Definitions from OpenApi documentation correctly options.UseAllOfToExtendReferenceSchemas(); - // if you want to add xml comments (with remarks) into the swagger documentation, first of all add: + // if you want to add xml comments from summary and remarks into the swagger documentation, first of all add: + // you can exclude remarks for concrete types var xmlFilePath = Path.Combine(AppContext.BaseDirectory, "WebApi3.1-Swashbuckle.xml"); - options.IncludeXmlCommentsWithRemarks(xmlFilePath); + options.IncludeXmlCommentsWithRemarks(xmlFilePath, false, + typeof(ComplicatedClass), + typeof(InnerEnum)); + // or add without remarks //options.IncludeXmlComments(xmlFilePath); @@ -336,6 +340,13 @@ public void ConfigureServices(IServiceCollection services) // add xml comments from summary and remarks into the swagger documentation options.IncludeXmlCommentsWithRemarks(""); + // add xml comments from summary and remarks into the swagger documentation + // with excluding remarks for concrete types (since v2.4.1) + var xmlFilePath = Path.Combine(AppContext.BaseDirectory, "WebApi3.1-Swashbuckle.xml"); + options.IncludeXmlCommentsWithRemarks(xmlFilePath, false, + typeof(ComplicatedClass), + typeof(InnerEnum)); + ... }); } diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/SwaggerGenOptionsExtensions.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/SwaggerGenOptionsExtensions.cs index 6803d54..d1ca0dc 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/SwaggerGenOptionsExtensions.cs +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/SwaggerGenOptionsExtensions.cs @@ -1,4 +1,5 @@ using System; +using System.Linq; using System.Net; using System.Xml.XPath; using Microsoft.Extensions.DependencyInjection; @@ -95,20 +96,24 @@ void EmptyAction(FixEnumsOptions x) { } /// 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. /// + /// Types for which remarks will be excluded. public static SwaggerGenOptions IncludeXmlCommentsWithRemarks( this SwaggerGenOptions swaggerGenOptions, Func xmlDocFactory, - bool includeControllerXmlComments = false) + bool includeControllerXmlComments = false, + params Type[] excludedTypes) { swaggerGenOptions.IncludeXmlComments(xmlDocFactory, includeControllerXmlComments); + var distinctExcludedTypes = excludedTypes.Distinct().ToList(); + var xmlDoc = xmlDocFactory(); - swaggerGenOptions.ParameterFilter(xmlDoc); - swaggerGenOptions.RequestBodyFilter(xmlDoc); - swaggerGenOptions.SchemaFilter(xmlDoc); + swaggerGenOptions.ParameterFilter(xmlDoc, distinctExcludedTypes); + swaggerGenOptions.RequestBodyFilter(xmlDoc, distinctExcludedTypes); + swaggerGenOptions.SchemaFilter(xmlDoc, distinctExcludedTypes); if (includeControllerXmlComments) - swaggerGenOptions.DocumentFilter(xmlDoc); + swaggerGenOptions.DocumentFilter(xmlDoc, distinctExcludedTypes); return swaggerGenOptions; } @@ -122,12 +127,14 @@ public static SwaggerGenOptions IncludeXmlCommentsWithRemarks( /// 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. /// + /// Types for which remarks will be excluded. public static SwaggerGenOptions IncludeXmlCommentsWithRemarks( this SwaggerGenOptions swaggerGenOptions, string filePath, - bool includeControllerXmlComments = false) + bool includeControllerXmlComments = false, + params Type[] excludedTypes) { - return swaggerGenOptions.IncludeXmlCommentsWithRemarks(() => new XPathDocument(filePath), includeControllerXmlComments); + return swaggerGenOptions.IncludeXmlCommentsWithRemarks(() => new XPathDocument(filePath), includeControllerXmlComments, excludedTypes); } #endregion diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksDocumentFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksDocumentFilter.cs index 31ab75e..0b24586 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksDocumentFilter.cs +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksDocumentFilter.cs @@ -18,8 +18,8 @@ public class XmlCommentsWithRemarksDocumentFilter : IDocumentFilter private const string MemberXPath = "/doc/members/member[@name='{0}']"; private const string SummaryTag = "summary"; private const string RemarksTag = "remarks"; - private readonly XPathNavigator _xmlNavigator; + private readonly Type[] _excludedTypes; #endregion @@ -29,9 +29,11 @@ public class XmlCommentsWithRemarksDocumentFilter : IDocumentFilter /// Constructor. /// /// - public XmlCommentsWithRemarksDocumentFilter(XPathDocument xmlDoc) + /// Excluded types. + public XmlCommentsWithRemarksDocumentFilter(XPathDocument xmlDoc, params Type[] excludedTypes) { _xmlNavigator = xmlDoc.CreateNavigator(); + _excludedTypes = excludedTypes; } #endregion @@ -54,6 +56,12 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context) foreach (var nameAndType in controllerNamesAndTypes) { + if (_excludedTypes.ToList().Select(t => t.FullName) + .Contains(nameAndType.Value.FullName)) + { + continue; + } + var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(nameAndType.Value); var typeNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, memberName)); diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksParameterFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksParameterFilter.cs index 3f50eff..ce2d133 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksParameterFilter.cs +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksParameterFilter.cs @@ -1,4 +1,6 @@ -using System.Reflection; +using System; +using System.Linq; +using System.Reflection; using System.Xml.XPath; using Microsoft.OpenApi.Models; using Swashbuckle.AspNetCore.SwaggerGen; @@ -15,6 +17,7 @@ public class XmlCommentsWithRemarksParameterFilter : IParameterFilter private const string SummaryTag = "summary"; private const string RemarksTag = "remarks"; private readonly XPathNavigator _xmlNavigator; + private readonly Type[] _excludedTypes; #endregion @@ -24,9 +27,11 @@ public class XmlCommentsWithRemarksParameterFilter : IParameterFilter /// Constructor. /// /// - public XmlCommentsWithRemarksParameterFilter(XPathDocument xmlDoc) + /// Excluded types. + public XmlCommentsWithRemarksParameterFilter(XPathDocument xmlDoc, params Type[] excludedTypes) { _xmlNavigator = xmlDoc.CreateNavigator(); + _excludedTypes = excludedTypes; } #endregion @@ -48,6 +53,12 @@ public void Apply(OpenApiParameter parameter, ParameterFilterContext context) private void ApplyPropertyTags(OpenApiParameter parameter, PropertyInfo propertyInfo) { + if (propertyInfo.DeclaringType != null && _excludedTypes.ToList().Select(t => t.FullName) + .Contains(propertyInfo.DeclaringType?.FullName)) + { + return; + } + var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo); var propertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']"); diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksRequestBodyFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksRequestBodyFilter.cs index cc00e07..3f4266d 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksRequestBodyFilter.cs +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksRequestBodyFilter.cs @@ -1,4 +1,6 @@ -using System.Reflection; +using System; +using System.Linq; +using System.Reflection; using System.Xml.XPath; using Microsoft.OpenApi.Models; using Swashbuckle.AspNetCore.SwaggerGen; @@ -15,6 +17,7 @@ public class XmlCommentsWithRemarksRequestBodyFilter : IRequestBodyFilter private const string SummaryTag = "summary"; private const string RemarksTag = "remarks"; private readonly XPathNavigator _xmlNavigator; + private readonly Type[] _excludedTypes; #endregion @@ -24,9 +27,11 @@ public class XmlCommentsWithRemarksRequestBodyFilter : IRequestBodyFilter /// Constructor. /// /// - public XmlCommentsWithRemarksRequestBodyFilter(XPathDocument xmlDoc) + /// Excluded types. + public XmlCommentsWithRemarksRequestBodyFilter(XPathDocument xmlDoc, params Type[] excludedTypes) { _xmlNavigator = xmlDoc.CreateNavigator(); + _excludedTypes = excludedTypes; } #endregion @@ -54,6 +59,12 @@ public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext conte private void ApplyPropertyTags(OpenApiRequestBody requestBody, PropertyInfo propertyInfo) { + if (propertyInfo.DeclaringType != null && _excludedTypes.ToList().Select(t => t.FullName) + .Contains(propertyInfo.DeclaringType?.FullName)) + { + return; + } + var propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(propertyInfo); var propertySummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{propertyMemberName}']/{SummaryTag}"); diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksSchemaFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksSchemaFilter.cs index 3cc5586..c66f442 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksSchemaFilter.cs +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XmlCommentsWithRemarksSchemaFilter.cs @@ -1,4 +1,5 @@ using System; +using System.Linq; using System.Reflection; using System.Xml.XPath; using Microsoft.OpenApi.Models; @@ -16,6 +17,7 @@ public class XmlCommentsWithRemarksSchemaFilter : ISchemaFilter private const string SummaryTag = "summary"; private const string RemarksTag = "remarks"; private readonly XPathNavigator _xmlNavigator; + private readonly Type[] _excludedTypes; #endregion @@ -25,9 +27,11 @@ public class XmlCommentsWithRemarksSchemaFilter : ISchemaFilter /// Constructor. /// /// - public XmlCommentsWithRemarksSchemaFilter(XPathDocument xmlDoc) + /// Excluded types. + public XmlCommentsWithRemarksSchemaFilter(XPathDocument xmlDoc, params Type[] excludedTypes) { _xmlNavigator = xmlDoc.CreateNavigator(); + _excludedTypes = excludedTypes; } #endregion @@ -55,9 +59,14 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context) private void ApplyTypeTags(OpenApiSchema schema, Type type) { + if (_excludedTypes.ToList().Select(t => t.FullName) + .Contains(type.FullName)) + { + return; + } + var typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(type); var typeSummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{typeMemberName}']/{SummaryTag}"); - if (typeSummaryNode != null) { var typeRemarksNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{typeMemberName}']/{RemarksTag}"); @@ -71,9 +80,14 @@ private void ApplyTypeTags(OpenApiSchema schema, Type type) private void ApplyFieldOrPropertyTags(OpenApiSchema schema, MemberInfo fieldOrPropertyInfo) { + if (fieldOrPropertyInfo.DeclaringType != null && _excludedTypes.ToList().Select(t => t.FullName) + .Contains(fieldOrPropertyInfo.DeclaringType?.FullName)) + { + return; + } + var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(fieldOrPropertyInfo); var fieldOrPropertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{fieldOrPropertyMemberName}']"); - var summaryNode = fieldOrPropertyNode?.SelectSingleNode(SummaryTag); if (summaryNode != null) { diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.csproj b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.csproj index b13542b..f5ccaeb 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.csproj +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.csproj @@ -14,9 +14,9 @@ 7.3 https://github.com/unchase/Unchase.Swashbuckle.AspNetCore.Extensions/blob/master/assets/icon.png?raw=true - 2.4.0 - 2.4.0.0 - 2.4.0.0 + 2.4.1 + 2.4.1.0 + 2.4.1.0 false Unchase.Swashbuckle.AspNetCore.Extensions.xml diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml index 42d850c..69c9947 100644 --- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml +++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml @@ -103,7 +103,7 @@ An to configure options for filters. - + Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML Comment files (from summary and remarks). @@ -113,8 +113,9 @@ 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. + Types for which remarks will be excluded. - + Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML Comment files (from summary and remarks). @@ -124,6 +125,7 @@ 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. + Types for which remarks will be excluded. @@ -358,11 +360,12 @@ Inject human-friendly remarks to descriptions for Document's Tags based on XML Comment files. - + Constructor. + Excluded types. @@ -376,11 +379,12 @@ Inject human-friendly remarks to descriptions for Parameters based on XML Comment files. - + Constructor. + Excluded types. @@ -394,11 +398,12 @@ Inject human-friendly remarks to descriptions for RequestBodies based on XML Comment files. - + Constructor. + Excluded types. @@ -412,11 +417,12 @@ Inject human-friendly remarks to descriptions for Schemas based on XML Comment files. - + Constructor. + Excluded types. diff --git a/test/WebApi3.1-Swashbuckle/Startup.cs b/test/WebApi3.1-Swashbuckle/Startup.cs index 55d0b00..5940d2e 100644 --- a/test/WebApi3.1-Swashbuckle/Startup.cs +++ b/test/WebApi3.1-Swashbuckle/Startup.cs @@ -37,8 +37,12 @@ public void ConfigureServices(IServiceCollection services) #region AddEnumsWithValuesFixFilters // if you want to add xml comments from summary and remarks into the swagger documentation, first of all add: + // you can exclude remarks for concrete types var xmlFilePath = Path.Combine(AppContext.BaseDirectory, "WebApi3.1-Swashbuckle.xml"); - options.IncludeXmlCommentsWithRemarks(xmlFilePath); + options.IncludeXmlCommentsWithRemarks(xmlFilePath, false, + typeof(ComplicatedClass), + typeof(InnerEnum)); + // or add without remarks //options.IncludeXmlComments(xmlFilePath);