From c48232cfa09ade23aa2b1addbddd2d0e5bebe502 Mon Sep 17 00:00:00 2001
From: Chebotov Nikolay <spiritkola@hotmail.com>
Date: Wed, 25 Mar 2020 16:37:37 +0300
Subject: [PATCH] Add option to choose descriptions source -
 "FixEnumOptions.DescriptionSource"; Fix small bugs.

---
 CHANGELOG.md                                  |  5 ++
 README.md                                     |  3 +
 .../Extensions/EnumTypeExtensions.cs          | 80 ++++++++++++++-----
 .../Filters/XEnumNamesParameterFilter.cs      |  6 +-
 .../Filters/XEnumNamesSchemaFilter.cs         |  6 +-
 .../Options/FixEnumsOptions.cs                |  6 ++
 ...e.Swashbuckle.AspNetCore.Extensions.csproj |  6 +-
 ...hase.Swashbuckle.AspNetCore.Extensions.xml | 25 ++++++
 test/WebApi3.1-Swashbuckle/Startup.cs         |  3 +
 9 files changed, 113 insertions(+), 27 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ba18e52..0887da6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,11 @@
 
 These are the changes to each version that has been released on the [nuget](https://www.nuget.org/packages/Unchase.Swashbuckle.AspNetCore.Extensions/).
 
+## v2.3.3 `(2020-03-25)`
+
+- [x] Add option to choose descriptions source - `FixEnumOptions.DescriptionSource`
+- [x] Fix small bugs
+
 ## v2.3.2 `(2020-03-25)`
 
 - [x] Fix bug with `System.MissingMethodException`
diff --git a/README.md b/README.md
index 3d61423..07d6f64 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,9 @@ public void ConfigureServices(IServiceCollection services)
             // add descriptions from DescriptionAttribute or xml-comments to fix enums (add 'x-enumDescriptions' for schema extensions) for applied filters
             o.IncludeDescriptions = true;
 
+            // get descriptions from DescriptionAttribute then from xml-comments
+            o.DescriptionSource = DescriptionSources.DescriptionAttributesThenXmlComments;
+
             // get descriptions from xml-file comments on the specified path
             // should use "options.IncludeXmlComments(xmlFilePath);" before
             o.IncludeXmlCommentsFrom(xmlFilePath);
diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs
index 219e942..ea8ec5d 100644
--- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs
+++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs
@@ -11,6 +11,27 @@
 
 namespace Unchase.Swashbuckle.AspNetCore.Extensions.Extensions
 {
+    /// <summary>
+    /// Description sources.
+    /// </summary>
+    public enum DescriptionSources
+    {
+        /// <summary>
+        /// <see cref="DescriptionAttribute"/>.
+        /// </summary>
+        DescriptionAttributes = 0,
+
+        /// <summary>
+        /// Xml comments.
+        /// </summary>
+        XmlComments = 1,
+
+        /// <summary>
+        /// <see cref="DescriptionAttribute"/> then xml comments.
+        /// </summary>
+        DescriptionAttributesThenXmlComments = 2
+    }
+
     internal static class EnumTypeExtensions
     {
         private static string GetDescriptionFromEnumOption(Type enumOptionType, object enumOption)
@@ -29,18 +50,43 @@ private static string GetFieldAttributeDescription(this Type enumType, object en
             return string.Empty;
         }
 
-        internal static List<OpenApiString> GetEnumValuesDescription(Type enumType, IEnumerable<XPathNavigator> xmlNavigators = null)
+        internal static List<OpenApiString> GetEnumValuesDescription(Type enumType, DescriptionSources descriptionSource, IEnumerable<XPathNavigator> xmlNavigators = null)
         {
             var enumsDescriptions = new List<OpenApiString>();
             foreach (var enumValue in Enum.GetValues(enumType))
             {
-                var enumDescription = GetDescriptionFromEnumOption(enumType, enumValue);
-                if (string.IsNullOrWhiteSpace(enumDescription))
+                var enumDescription = string.Empty;
+                try
                 {
-                    var memberInfo = enumType.GetMembers().FirstOrDefault(m => m.Name.Equals(enumValue.ToString(), StringComparison.InvariantCultureIgnoreCase));
-                    enumDescription = TryGetMemberComments(memberInfo, xmlNavigators);
+                    switch (descriptionSource)
+                    {
+                        case DescriptionSources.DescriptionAttributes:
+                            enumDescription = GetDescriptionFromEnumOption(enumType, enumValue);
+                            break;
+                        case DescriptionSources.XmlComments:
+                            var memberInfo = enumType.GetMembers().FirstOrDefault(m =>
+                                m.Name.Equals(enumValue.ToString(), StringComparison.InvariantCultureIgnoreCase));
+                            enumDescription = TryGetMemberComments(memberInfo, xmlNavigators);
+                            break;
+                        case DescriptionSources.DescriptionAttributesThenXmlComments:
+                            enumDescription = GetDescriptionFromEnumOption(enumType, enumValue);
+                            if (string.IsNullOrWhiteSpace(enumDescription))
+                            {
+                                var memberInfo2 = enumType.GetMembers().FirstOrDefault(m =>
+                                    m.Name.Equals(enumValue.ToString(), StringComparison.InvariantCultureIgnoreCase));
+                                enumDescription = TryGetMemberComments(memberInfo2, xmlNavigators);
+                            }
+                            break;
+                    }
+                }
+                catch
+                {
+
+                }
+                finally
+                {
+                    enumsDescriptions.Add(new OpenApiString(enumDescription));
                 }
-                enumsDescriptions.Add(new OpenApiString(enumDescription));
             }
             return enumsDescriptions;
         }
@@ -50,20 +96,13 @@ private static string TryGetMemberComments(MemberInfo memberInfo, IEnumerable<XP
             if (xmlNavigators == null)
                 return string.Empty;
 
-            try
-            {
-                foreach (var xmlNavigator in xmlNavigators)
-                {
-                    var nodeNameForMember = XmlCommentsNodeNameHelper.GetNodeNameForMember(memberInfo);
-                    var xpathNavigator1 = xmlNavigator.SelectSingleNode(
-                        $"/doc/members/member[@name='{nodeNameForMember}']");
-                    var xpathNavigator2 = xpathNavigator1?.SelectSingleNode("summary");
-                    return xpathNavigator2 != null ? XmlCommentsTextHelper.Humanize(xpathNavigator2.InnerXml) : string.Empty;
-                }
-            }
-            catch
+            foreach (var xmlNavigator in xmlNavigators)
             {
-                return string.Empty;
+                var nodeNameForMember = XmlCommentsNodeNameHelper.GetNodeNameForMember(memberInfo);
+                var xpathNavigator1 = xmlNavigator.SelectSingleNode(
+                    $"/doc/members/member[@name='{nodeNameForMember}']");
+                var xpathNavigator2 = xpathNavigator1?.SelectSingleNode("summary");
+                return xpathNavigator2 != null ? XmlCommentsTextHelper.Humanize(xpathNavigator2.InnerXml) : string.Empty;
             }
 
             return string.Empty;
@@ -102,7 +141,8 @@ internal static string AddEnumValuesDescription(this OpenApiSchema schema, bool
                     if (xEnumDescriptions?.Count == schema.Enum.Count)
                     {
                         var description = ((OpenApiString)((OpenApiArray)schema.Extensions["x-enumDescriptions"])[i]).Value;
-                        sb.Append($" ({description})");
+                        if (!string.IsNullOrWhiteSpace(description))
+                            sb.Append($" ({description})");
                     }
                 }
             }
diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesParameterFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesParameterFilter.cs
index 7067948..1e40acc 100644
--- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesParameterFilter.cs
+++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesParameterFilter.cs
@@ -17,6 +17,7 @@ internal class XEnumNamesParameterFilter : IParameterFilter
         #region Fields
 
         private readonly bool _includeXEnumDescriptions;
+        private readonly DescriptionSources _descriptionSources;
         private readonly bool _applyFiler;
         private readonly HashSet<XPathNavigator> _xmlNavigators = new HashSet<XPathNavigator>();
 
@@ -35,6 +36,7 @@ public XEnumNamesParameterFilter(IOptions<FixEnumsOptions> options, Action<FixEn
             {
                 configureOptions?.Invoke(options.Value);
                 this._includeXEnumDescriptions = options.Value?.IncludeDescriptions ?? false;
+                this._descriptionSources = options.Value?.DescriptionSource ?? DescriptionSources.DescriptionAttributes;
                 this._applyFiler = options.Value?.ApplyParameterFilter ?? false;
                 foreach (var filePath in options.Value?.IncludedXmlCommentsPaths)
                 {
@@ -74,7 +76,7 @@ public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
 
                 if (this._includeXEnumDescriptions)
                 {
-                    enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(typeInfo, this._xmlNavigators));
+                    enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(typeInfo, this._descriptionSources, this._xmlNavigators));
                     if (!parameter.Extensions.ContainsKey("x-enumDescriptions") && enumsDescriptionsArray.Any())
                     {
                         parameter.Extensions.Add("x-enumDescriptions", enumsDescriptionsArray);
@@ -96,7 +98,7 @@ public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
 
                         if (this._includeXEnumDescriptions)
                         {
-                            enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(genericArgumentType, this._xmlNavigators));
+                            enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(genericArgumentType, this._descriptionSources, this._xmlNavigators));
                             if (!parameter.Extensions.ContainsKey("x-enumDescriptions") && enumsDescriptionsArray.Any())
                             {
                                 parameter.Extensions.Add("x-enumDescriptions", enumsDescriptionsArray);
diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesSchemaFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesSchemaFilter.cs
index 304687c..250ae02 100644
--- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesSchemaFilter.cs
+++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/XEnumNamesSchemaFilter.cs
@@ -18,6 +18,7 @@ internal class XEnumNamesSchemaFilter : ISchemaFilter
         #region Fields
 
         private readonly bool _includeXEnumDescriptions;
+        private readonly DescriptionSources _descriptionSources;
         private readonly bool _applyFiler;
         private readonly HashSet<XPathNavigator> _xmlNavigators = new HashSet<XPathNavigator>();
 
@@ -36,6 +37,7 @@ public XEnumNamesSchemaFilter(IOptions<FixEnumsOptions> options, Action<FixEnums
             {
                 configureOptions?.Invoke(options.Value);
                 this._includeXEnumDescriptions = options.Value.IncludeDescriptions;
+                this._descriptionSources = options.Value?.DescriptionSource ?? DescriptionSources.DescriptionAttributes;
                 this._applyFiler = options.Value.ApplySchemaFilter;
                 foreach (var filePath in options.Value.IncludedXmlCommentsPaths)
                 {
@@ -75,7 +77,7 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
 
                 if (this._includeXEnumDescriptions)
                 {
-                    enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(context.Type, this._xmlNavigators));
+                    enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(context.Type, this._descriptionSources, this._xmlNavigators));
                     if (!schema.Extensions.ContainsKey("x-enumDescriptions") && enumsDescriptionsArray.Any())
                     {
                         schema.Extensions.Add("x-enumDescriptions", enumsDescriptionsArray);
@@ -108,7 +110,7 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
 
                                     if (this._includeXEnumDescriptions)
                                     {
-                                        enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(genericArgumentType, this._xmlNavigators));
+                                        enumsDescriptionsArray.AddRange(EnumTypeExtensions.GetEnumValuesDescription(genericArgumentType, this._descriptionSources, this._xmlNavigators));
                                         if (!schemaPropertyValue.Extensions.ContainsKey("x-enumDescriptions") && enumsDescriptionsArray.Any())
                                         {
                                             schemaPropertyValue.Extensions.Add("x-enumDescriptions", enumsDescriptionsArray);
diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Options/FixEnumsOptions.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Options/FixEnumsOptions.cs
index 286f68f..0fae42a 100644
--- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Options/FixEnumsOptions.cs
+++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Options/FixEnumsOptions.cs
@@ -1,5 +1,6 @@
 using System.Collections.Generic;
 using System.ComponentModel;
+using Unchase.Swashbuckle.AspNetCore.Extensions.Extensions;
 
 namespace Unchase.Swashbuckle.AspNetCore.Extensions.Options
 {
@@ -20,6 +21,11 @@ public class FixEnumsOptions
         /// </summary>
         public bool IncludeDescriptions { get; set; } = false;
 
+        /// <summary>
+        /// Source to get descriptions. Default value is <see cref="DescriptionSources.DescriptionAttributes"/>.
+        /// </summary>
+        public DescriptionSources DescriptionSource { get; set; } = DescriptionSources.DescriptionAttributes;
+
         /// <summary>
         /// Apply fix enum filter to OpenApi schema. Default value is true.
         /// <para>
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 8497f4e..35e209a 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 @@
     <NeutralLanguage></NeutralLanguage>
     <LangVersion>7.3</LangVersion>
     <PackageIconUrl>https://github.com/unchase/Unchase.Swashbuckle.AspNetCore.Extensions/blob/master/assets/icon.png?raw=true</PackageIconUrl>
-    <Version>2.3.2</Version>
-    <AssemblyVersion>2.3.2.0</AssemblyVersion>
-    <FileVersion>2.3.2.0</FileVersion>
+    <Version>2.3.3</Version>
+    <AssemblyVersion>2.3.3.0</AssemblyVersion>
+    <FileVersion>2.3.3.0</FileVersion>
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
     <DocumentationFile>Unchase.Swashbuckle.AspNetCore.Extensions.xml</DocumentationFile>
   </PropertyGroup>
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 3b1ff2a..f7f42bb 100644
--- a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml
+++ b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.xml
@@ -4,6 +4,26 @@
         <name>Unchase.Swashbuckle.AspNetCore.Extensions</name>
     </assembly>
     <members>
+        <member name="T:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.DescriptionSources">
+            <summary>
+            Description sources.
+            </summary>
+        </member>
+        <member name="F:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.DescriptionSources.DescriptionAttributes">
+            <summary>
+            <see cref="T:System.ComponentModel.DescriptionAttribute"/>.
+            </summary>
+        </member>
+        <member name="F:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.DescriptionSources.XmlComments">
+            <summary>
+            Xml comments.
+            </summary>
+        </member>
+        <member name="F:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.DescriptionSources.DescriptionAttributesThenXmlComments">
+            <summary>
+            <see cref="T:System.ComponentModel.DescriptionAttribute"/> then xml comments.
+            </summary>
+        </member>
         <member name="T:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.OpenApiDocumentExtensions">
             <summary>
             Extension methods for <see cref="T:Microsoft.OpenApi.Models.OpenApiDocument"/>.
@@ -290,6 +310,11 @@
             Include descriptions from <see cref="T:System.ComponentModel.DescriptionAttribute"/> or xml comments. Default value is false.
             </summary>
         </member>
+        <member name="P:Unchase.Swashbuckle.AspNetCore.Extensions.Options.FixEnumsOptions.DescriptionSource">
+            <summary>
+            Source to get descriptions. Default value is <see cref="F:Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.DescriptionSources.DescriptionAttributes"/>.
+            </summary>
+        </member>
         <member name="P:Unchase.Swashbuckle.AspNetCore.Extensions.Options.FixEnumsOptions.ApplySchemaFilter">
             <summary>
             Apply fix enum filter to OpenApi schema. Default value is true.
diff --git a/test/WebApi3.1-Swashbuckle/Startup.cs b/test/WebApi3.1-Swashbuckle/Startup.cs
index f9add5c..48d5ac9 100644
--- a/test/WebApi3.1-Swashbuckle/Startup.cs
+++ b/test/WebApi3.1-Swashbuckle/Startup.cs
@@ -56,6 +56,9 @@ public void ConfigureServices(IServiceCollection services)
                     // add descriptions from DescriptionAttribute or xml-comments to fix enums (add 'x-enumDescriptions' for schema extensions) for applied filters
                     o.IncludeDescriptions = true;
 
+                    // get descriptions from DescriptionAttribute then from xml-comments
+                    o.DescriptionSource = DescriptionSources.DescriptionAttributesThenXmlComments;
+
                     // get descriptions from xml-file comments on the specified path
                     // should use "options.IncludeXmlComments(xmlFilePath);" before
                     o.IncludeXmlCommentsFrom(xmlFilePath);