Fix some bugs in IncludeXmlCommentsWithRemarks option;

Add `IncludeXmlCommentsFromInheritDocs` option to add xml comments from inheritdocs (from summary and remarks) into the swagger documentation.

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.5.0 `2020-10-15`
+
+- [x] Fix some bugs in `IncludeXmlCommentsWithRemarks` option
+- [x] Add `IncludeXmlCommentsFromInheritDocs` option to add xml comments from inheritdocs (from summary and remarks) into the swagger documentation
+
 ## v2.4.1 `2020-10-13`
 
 - [x] Add `params Type[]` parameters to `IncludeXmlCommentsWithRemarks` option to exclude remarks for concrete types

README.md

@@ -101,6 +101,10 @@ 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 from inheritdocs (from summary and remarks) into the swagger documentation, add:
+        // you can exclude remarks for concrete types
+        options.IncludeXmlCommentsFromInheritDocs(includeRemarks: true, excludedTypes: typeof(string));
+
         // 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");
@@ -352,6 +356,29 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
+7. **Add xml comments from <inheritdoc/> (from summary and remarks) into the swagger documentation**:
+
+- Since [v2.5.0](https://github.com/unchase/Unchase.Swashbuckle.AspNetCore.Extensions/releases/tag/v2.5.0) in the _ConfigureServices_ method of _Startup.cs_, inside your `AddSwaggerGen` call, add `IncludeXmlCommentsFromInheritDocs` option:
+
+```csharp
+// This method gets called by the runtime. Use this method to add services to the container.
+public void ConfigureServices(IServiceCollection services)
+{
+    ...
+
+    services.AddSwaggerGen(options =>
+    {
+        ...
+
+        // add xml comments from inheritdocs (from summary and remarks) into the swagger documentation, add:
+        // with excluding concrete types
+        options.IncludeXmlCommentsFromInheritDocs(includeRemarks: true, excludedTypes: typeof(string));
+
+        ...
+    });
+}
+```
+
 ## Builds status
 
 |Status|Value|
@@ -600,6 +627,83 @@ public enum SecondInnerEnum
 }
 ```
 
+### Add xml comments from <inheritdoc/> (from summary and remarks) into the swagger documentation
+
+![Add xml comments from ingeritdoc](assets/addXmlCommentsFromInheritdoc.png)
+
+For code:
+
+```csharp
+/// <inheritdoc cref="IInheritDocClass"/>
+public class InheritDocClass : IInheritDocClass
+{
+    /// <inheritdoc/>
+    public string Name { get; set; }
+
+    /// <inheritdoc/>
+    public string Common { get; set; }
+
+    /// <inheritdoc/>
+    public InheritEnum InheritEnum { get; set; }
+}
+
+/// <summary>
+/// InheritDocClass - inheritdoc
+/// </summary>
+/// <remarks>
+/// InheritDocClass remarks - inheritdoc
+/// </remarks>
+public interface IInheritDocClass : IInheritDocCommon
+{
+    /// <summary>
+    /// Name - inheritdoc
+    /// </summary>
+    /// <remarks>
+    /// Name remarks - inheritdoc
+    /// </remarks>
+    public string Name { get; set; }
+}
+
+/// <summary>
+/// IInheritDocCommon interface
+/// </summary>
+/// <remarks>
+/// IInheritDocCommon interface remarks
+/// </remarks>
+public interface IInheritDocCommon
+{
+    /// <summary>
+    /// Common - inheritdoc (inner)
+    /// </summary>
+    /// <remarks>
+    /// Common remarks - inheritdoc (inner)
+    /// </remarks>
+    public string Common { get; set; }
+
+    /// <summary>
+    /// InheritEnum - inheritdoc (inner)
+    /// </summary>
+    public InheritEnum InheritEnum { get; set; }
+}
+
+/// <summary>
+/// Inherit enum - enum
+/// </summary>
+/// <remarks>
+/// Inherit enum remarks - enum
+/// </remarks>
+public enum InheritEnum
+{
+    /// <summary>
+    /// Inherit enum Value
+    /// </summary>
+    /// <remarks>
+    /// Inherit enum Value remarks
+    /// </remarks>
+    Value = 0
+}
+```
+
 ## HowTos
 
 - [ ] Add HowTos in a future

Unchase.Swashbuckle.AspNetCore.Extensions.sln

@@ -10,6 +10,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{145A03BF-E60E-41F6-BD89-457F940F6C9B}"
 	ProjectSection(SolutionItems) = preProject
 		.gitignore = .gitignore
+		assets\addXmlCommentsFromInheritdoc.png = assets\addXmlCommentsFromInheritdoc.png
 		assets\addXmlCommentsFromSummaryAndRemarks.png = assets\addXmlCommentsFromSummaryAndRemarks.png
 		assets\appendActionCountIntoSwaggerTag.png = assets\appendActionCountIntoSwaggerTag.png
 		appveyor.yml = appveyor.yml

appveyor.yml

@@ -1,4 +1,4 @@
-version: 2.4.{build}
+version: 2.5.{build}
 pull_requests:
   do_not_increment_build_number: true
 skip_tags: true

src/Unchase.Swashbuckle.AspNetCore.Extensions/Extensions/SwaggerGenOptionsExtensions.cs

@@ -105,7 +105,7 @@ public static SwaggerGenOptions IncludeXmlCommentsWithRemarks(
         {
             swaggerGenOptions.IncludeXmlComments(xmlDocFactory, includeControllerXmlComments);
 
-            var distinctExcludedTypes = excludedTypes.Distinct().ToList();
+            var distinctExcludedTypes = excludedTypes?.Distinct().ToArray();
 
             var xmlDoc = xmlDocFactory();
             swaggerGenOptions.ParameterFilter<XmlCommentsWithRemarksParameterFilter>(xmlDoc, distinctExcludedTypes);
@@ -137,6 +137,24 @@ public static SwaggerGenOptions IncludeXmlCommentsWithRemarks(
             return swaggerGenOptions.IncludeXmlCommentsWithRemarks(() => new XPathDocument(filePath), includeControllerXmlComments, excludedTypes);
         }
 
+        /// <summary>
+        /// Inject human-friendly descriptions for Schemas and it's Parameters based on &lt;inheritdoc/&gt; XML Comments (from summary and remarks).
+        /// </summary>
+        /// <param name="swaggerGenOptions"><see cref="SwaggerGenOptions"/>.</param>
+        /// <param name="includeRemarks">
+        /// Flag to indicate to include remarks from XML comments.
+        /// </param>
+        /// <param name="excludedTypes">Types for which remarks will be excluded.</param>
+        public static SwaggerGenOptions IncludeXmlCommentsFromInheritDocs(
+            this SwaggerGenOptions swaggerGenOptions,
+            bool includeRemarks = false,
+            params Type[] excludedTypes)
+        {
+            var distinctExcludedTypes = excludedTypes?.Distinct().ToArray();
+            swaggerGenOptions.SchemaFilter<InheritDocSchemaFilter>(swaggerGenOptions, includeRemarks, distinctExcludedTypes);
+            return swaggerGenOptions;
+        }
+
         #endregion
     }
 }