update: Add IncludeXmlCommentsWithRemarks improvements

unchase · Aug 26, 2021 · 2af9003 · 2af9003
1 parent 7d07e99
commit 2af9003
Show file tree

Hide file tree

Showing 10 changed files with 256 additions and 29 deletions.
diff --git 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.6.6 `2021-08-26`
+
+- [x] Add `IncludeXmlCommentsWithRemarks` improvements
+
 ## v2.6.3 `2021-08-26`
 
 - [x] Fix `IncludeXmlCommentsWithRemarks`

diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/EnumTypeExtensions.cs
@@ -139,7 +139,7 @@ private static string QualifiedNameFor(Type type, bool expandGenericArgs = false
                 return QualifiedNameFor(type.GetElementType(), expandGenericArgs) + "[]";
 
             var stringBuilder = new StringBuilder();
-            if (!string.IsNullOrEmpty(type.Namespace))
+            if (!string.IsNullOrWhiteSpace(type.Namespace))
                 stringBuilder.Append(type.Namespace + ".");
 
             if (type.IsNested)

diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/XmlCommentsExtensions.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/XmlCommentsExtensions.cs
@@ -57,7 +57,7 @@ private static Type[] GetTargets(Type type, string cref)
             }
 
             // Try to find the target, if one is declared.
-            if (!string.IsNullOrEmpty(cref))
+            if (!string.IsNullOrWhiteSpace(cref))
             {
                 var crefTarget = targets.SingleOrDefault(t => XmlCommentsNodeNameHelper.GetMemberNameForType(t) == cref);
 
@@ -124,7 +124,7 @@ private static MemberInfo[] GetTargets(MemberInfo memberInfo, string cref)
                 .ToList();
 
             // Try to find the target, if one is declared.
-            if (!string.IsNullOrEmpty(cref))
+            if (!string.IsNullOrWhiteSpace(cref))
             {
                 var crefTarget = targets.SingleOrDefault(t => XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(t) == cref);
 
@@ -164,21 +164,29 @@ internal static void ApplyPropertyComments(
             }
 
             string cref = inheritedDocs[memberName];
-            var target = memberInfo.GetTargetRecursive(inheritedDocs, cref);
-            if (target == null)
+            XPathNavigator targetXmlNode;
+            if (string.IsNullOrWhiteSpace(cref))
             {
-                return;
-            }
+                var target = memberInfo.GetTargetRecursive(inheritedDocs, cref);
+                if (target == null)
+                {
+                    return;
+                }
 
-            var targetXmlNode = GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(target), documents);
+                targetXmlNode = GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(target), documents);
+            }
+            else
+            {
+                targetXmlNode = GetMemberXmlNode(cref, documents);
+            }
 
             if (targetXmlNode == null)
             {
                 return;
             }
 
             var summaryNode = targetXmlNode.SelectSingleNode(SummaryTag);
-            if (summaryNode != null)
+            if (summaryNode != null && string.IsNullOrWhiteSpace(schema.Description))
             {
                 schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
 

diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocParameterFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocParameterFilter.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Reflection;
 using System.Xml.XPath;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
@@ -82,19 +83,26 @@ public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
 
             // Try to apply a description for inherited types.
             string parameterMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(context.ApiParameterDescription.PropertyInfo());
-            if (string.IsNullOrEmpty(parameter.Description) && _inheritedDocs.ContainsKey(parameterMemberName))
+            if (string.IsNullOrWhiteSpace(parameter.Description) && _inheritedDocs.ContainsKey(parameterMemberName))
             {
                 string cref = _inheritedDocs[parameterMemberName];
-                var target = context.ApiParameterDescription.PropertyInfo().GetTargetRecursive(_inheritedDocs, cref);
+                XPathNavigator targetXmlNode;
+                if (string.IsNullOrWhiteSpace(cref))
+                {
+                    var target = context.ApiParameterDescription.PropertyInfo().GetTargetRecursive(_inheritedDocs, cref);
+                    if (target == null)
+                    {
+                        return;
+                    }
 
-                if (target == null)
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(target), _documents);
+                }
+                else
                 {
-                    return;
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(cref, _documents);
                 }
 
-                var targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(target), _documents);
                 var summaryNode = targetXmlNode?.SelectSingleNode(SummaryTag);
-
                 if (summaryNode != null)
                 {
                     parameter.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
@@ -109,6 +117,32 @@ public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
                     }
                 }
             }
+
+            // TODO
+            var type = context.ApiParameterDescription.PropertyInfo()?.DeclaringType;
+            var typeName = type?.Name;
+            if (!string.IsNullOrWhiteSpace(typeName))
+            {
+                if (context.SchemaRepository.Schemas.ContainsKey(typeName))
+                {
+                    var schema = context.SchemaRepository.Schemas[typeName];
+                    if (schema?.Properties?.Any() != true)
+                    {
+                        return;
+                    }
+
+                    // Add the summary and examples for the properties.
+                    foreach (var entry in schema.Properties)
+                    {
+                        var memberInfo = ((TypeInfo)type).DeclaredMembers.FirstOrDefault(p =>
+                            p.Name.Equals(entry.Key, StringComparison.OrdinalIgnoreCase));
+                        if (memberInfo != null)
+                        {
+                            entry.Value.ApplyPropertyComments(memberInfo, _documents, _inheritedDocs, _includeRemarks, _excludedTypes);
+                        }
+                    }
+                }
+            }
         }
 
         #endregion

diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocRequestBodyFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocRequestBodyFilter.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Reflection;
 using System.Xml.XPath;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
@@ -72,14 +73,26 @@ public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext conte
 
             // Try to apply a description for inherited types.
             string parameterMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(context.BodyParameterDescription.Type);
-            if (string.IsNullOrEmpty(requestBody.Description) && _inheritedDocs.ContainsKey(parameterMemberName))
+            if (string.IsNullOrWhiteSpace(requestBody.Description) && _inheritedDocs.ContainsKey(parameterMemberName))
             {
                 string cref = _inheritedDocs[parameterMemberName];
-                var target = context.BodyParameterDescription.Type.GetTargetRecursive(_inheritedDocs, cref);
+                XPathNavigator targetXmlNode;
+                if (string.IsNullOrWhiteSpace(cref))
+                {
+                    var target = context.BodyParameterDescription.Type.GetTargetRecursive(_inheritedDocs, cref);
+                    if (target == null)
+                    {
+                        return;
+                    }
 
-                var targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForType(target), _documents);
-                var summaryNode = targetXmlNode?.SelectSingleNode(SummaryTag);
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForType(target), _documents);
+                }
+                else
+                {
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(cref, _documents);
+                }
 
+                var summaryNode = targetXmlNode?.SelectSingleNode(SummaryTag);
                 if (summaryNode != null)
                 {
                     requestBody.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
@@ -94,6 +107,26 @@ public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext conte
                     }
                 }
             }
+
+            if (context.SchemaRepository.Schemas.ContainsKey(context.BodyParameterDescription.Type.Name))
+            {
+                var schema = context.SchemaRepository.Schemas[context.BodyParameterDescription.Type.Name];
+                if (schema?.Properties?.Any() != true)
+                {
+                    return;
+                }
+
+                // Add the summary and examples for the properties.
+                foreach (var entry in schema.Properties)
+                {
+                    var memberInfo = ((TypeInfo)context.BodyParameterDescription.Type).DeclaredMembers.FirstOrDefault(p =>
+                        p.Name.Equals(entry.Key, StringComparison.OrdinalIgnoreCase));
+                    if (memberInfo != null)
+                    {
+                        entry.Value.ApplyPropertyComments(memberInfo, _documents, _inheritedDocs, _includeRemarks, _excludedTypes);
+                    }
+                }
+            }
         }
 
         #endregion

diff --git a/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocSchemaFilter.cs b/src/Unchase.Swashbuckle.AspNetCore.Extensions/Filters/InheritDocSchemaFilter.cs
@@ -73,19 +73,26 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
 
             // Try to apply a description for inherited types.
             string memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(context.Type);
-            if (string.IsNullOrEmpty(schema.Description) && _inheritedDocs.ContainsKey(memberName))
+            if (string.IsNullOrWhiteSpace(schema.Description) && _inheritedDocs.ContainsKey(memberName))
             {
                 string cref = _inheritedDocs[memberName];
-                var target = context.Type.GetTargetRecursive(_inheritedDocs, cref);
+                XPathNavigator targetXmlNode;
+                if (string.IsNullOrWhiteSpace(cref))
+                {
+                    var target = context.Type.GetTargetRecursive(_inheritedDocs, cref);
+                    if (target == null)
+                    {
+                        return;
+                    }
 
-                if (target == null)
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForType(target), _documents);
+                }
+                else
                 {
-                    return;
+                    targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(cref, _documents);
                 }
 
-                var targetXmlNode = XmlCommentsExtensions.GetMemberXmlNode(XmlCommentsNodeNameHelper.GetMemberNameForType(target), _documents);
                 var summaryNode = targetXmlNode?.SelectSingleNode(SummaryTag);
-
                 if (summaryNode != null)
                 {
                     schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
@@ -101,7 +108,7 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
                 }
             }
 
-            if (schema.Properties == null)
+            if (schema.Properties?.Any() != true)
             {
                 return;
             }

diff --git a/...nchase.Swashbuckle.AspNetCore.Extensions/Unchase.Swashbuckle.AspNetCore.Extensions.csproj b/...nchase.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.6.5</Version>
-    <AssemblyVersion>2.6.5.0</AssemblyVersion>
-    <FileVersion>2.6.5.0</FileVersion>
+    <Version>2.6.6</Version>
+    <AssemblyVersion>2.6.6.0</AssemblyVersion>
+    <FileVersion>2.6.6.0</FileVersion>
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
     <DocumentationFile>Unchase.Swashbuckle.AspNetCore.Extensions.xml</DocumentationFile>
   </PropertyGroup>

diff --git a/test/WebApi3.1-Swashbuckle/Controllers/TodoController.cs b/test/WebApi3.1-Swashbuckle/Controllers/TodoController.cs
@@ -3,6 +3,7 @@
 using Microsoft.AspNetCore.Mvc;
 using Swashbuckle.AspNetCore.Annotations;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 using TodoApi.Models;
 using WebApi3._1_Swashbuckle.Contexts;
 using WebApi3._1_Swashbuckle.Models;
@@ -149,5 +150,14 @@ public ActionResult<TodoItem> CreateFromQuery([FromQuery] TodoItem item)
 
             return new CreatedResult(string.Empty, item);
         }
+
+        /// <summary>
+        /// Add some command.
+        /// </summary>
+        [HttpPost("add-some-command")]
+        public IActionResult AddSomeCommand(AddSomeCommand command)
+        {
+            return Ok("Ok");
+        }
     }
 }
diff --git a/test/WebApi3.1-Swashbuckle/Models/AddSomeCommand.cs b/test/WebApi3.1-Swashbuckle/Models/AddSomeCommand.cs
@@ -0,0 +1,65 @@
+namespace WebApi3._1_Swashbuckle.Models
+{
+    /// <summary>
+    /// CommandType
+    /// </summary>
+    public class CommandType
+    {
+        /// <summary>
+        /// Name.
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// Description.
+        /// </summary>
+        public string Description { get; set; }
+
+        /// <summary>
+        /// External Id.
+        /// </summary>
+        public string ExternalId { get; set; }
+
+        /// <summary>
+        /// Is Read Only.
+        /// </summary>
+        /// <remarks>
+        /// Is Read Only remarks.
+        /// </remarks>
+        public bool IsReadOnly { get; set; }
+
+        /// <summary>
+        /// Is Active.
+        /// </summary>
+        /// <remarks>
+        /// Is Active remarks.
+        /// </remarks>
+        public bool IsActive { get; set; }
+    }
+
+    /// <summary>
+    /// AddSomeCommand.
+    /// </summary>
+    public class AddSomeCommand
+    {
+        /// <inheritdoc cref="CommandType.Name"/>
+        /// <example>Example</example>
+        public string Name { get; set; }
+
+        /// <inheritdoc cref="CommandType.Description"/>
+        /// <example>Example</example>
+        public string Description { get; set; }
+
+        /// <inheritdoc cref="CommandType.ExternalId"/>
+        /// <example>Example</example>
+        public string ExternalId { get; set; }
+
+        /// <inheritdoc cref="CommandType.IsReadOnly"/>
+        /// <example>false</example>
+        public bool IsReadOnly { get; set; }
+
+        /// <inheritdoc cref="CommandType.IsActive"/>
+        /// <example>true</example>
+        public bool IsActive { get; set; }
+    }
+}