Add UseXmlDocs setting (#1460)

* Add UseXmlDocs setting

* Update docs

* Use ResolveExternalXmlDocs

* Update NR

* Rename

src/NJsonSchema/Generation/IXmlDocsSettings.cs

@@ -0,0 +1,20 @@
+//-----------------------------------------------------------------------
+// <copyright file="IXmlDocsSettings.cs" company="NJsonSchema">
+//     Copyright (c) Rico Suter. All rights reserved.
+// </copyright>
+// <license>https://github.com/RicoSuter/NJsonSchema/blob/master/LICENSE.md</license>
+// <author>Rico Suter, [email protected]</author>
+//-----------------------------------------------------------------------
+
+namespace NJsonSchema.Generation
+{
+    /// <summary>The XML Docs related settings.</summary>
+    public interface IXmlDocsSettings
+    {
+        /// <summary>Gets or sets a value indicating whether to read XML Docs (default: true).</summary>
+        bool UseXmlDocumentation { get; }
+
+        /// <summary>Gets or sets a value indicating whether tho resolve the XML Docs from the NuGet cache or .NET SDK directory (default: true).</summary>
+        bool ResolveExternalXmlDocumentation { get; }
+    }
+}

src/NJsonSchema/Generation/JsonSchemaGenerator.cs

@@ -474,11 +474,11 @@ public virtual object ConvertDefaultValue(ContextualType type, object defaultVal
         /// <returns>The JToken or null.</returns>
         public virtual object GenerateExample(ContextualType type)
         {
-            if (Settings.GenerateExamples)
+            if (Settings.GenerateExamples && Settings.UseXmlDocumentation)
             {
                 try
                 {
-                    var docs = type.GetXmlDocsTag("example");
+                    var docs = type.GetXmlDocsTag("example", Settings.ResolveExternalXmlDocumentation);
                     return GenerateExample(docs);
                 }
                 catch
@@ -494,11 +494,11 @@ public virtual object GenerateExample(ContextualType type)
         /// <returns>The JToken or null.</returns>
         public virtual object GenerateExample(ContextualAccessorInfo accessorInfo)
         {
-            if (Settings.GenerateExamples)
+            if (Settings.GenerateExamples && Settings.UseXmlDocumentation)
             {
                 try
                 {
-                    var docs = accessorInfo.GetXmlDocsTag("example");
+                    var docs = accessorInfo.GetXmlDocsTag("example", Settings.ResolveExternalXmlDocumentation);
                     return GenerateExample(docs);
                 }
                 catch
@@ -551,7 +551,7 @@ protected virtual void GenerateObject(JsonSchema schema, JsonTypeDescription typ
                 typeDescription.ApplyType(schema);
             }
 
-            schema.Description = type.ToCachedType().GetDescription();
+            schema.Description = type.ToCachedType().GetDescription(Settings);
             schema.Example = GenerateExample(type.ToContextualType());
 
             dynamic obsoleteAttribute = type.GetTypeInfo().GetCustomAttributes(false).FirstAssignableToTypeNameOrDefault("System.ObsoleteAttribute");
@@ -861,10 +861,13 @@ private void GenerateEnum<TSchemaType>(
             else if (schema.GetType() == typeof(JsonSchema))
             {
                 typeDescription.ApplyType(schema);
-                schema.Description = type.GetXmlDocsSummary();
 
-                GenerateEnum(schema, typeDescription);
+                if (Settings.UseXmlDocumentation)
+                {
+                    schema.Description = type.GetXmlDocsSummary(Settings.ResolveExternalXmlDocumentation);
+                }
 
+                GenerateEnum(schema, typeDescription);
                 schemaResolver.AddSchema(type, isIntegerEnumeration, schema);
             }
             else
@@ -1278,7 +1281,7 @@ private void LoadPropertyOrField(JsonProperty jsonProperty, ContextualAccessorIn
 
                     if (propertySchema.Description == null)
                     {
-                        propertySchema.Description = accessorInfo.GetDescription();
+                        propertySchema.Description = accessorInfo.GetDescription(Settings);
                     }
 
                     if (propertySchema.Example == null)

src/NJsonSchema/Generation/JsonSchemaGeneratorSettings.cs

@@ -22,7 +22,7 @@
 namespace NJsonSchema.Generation
 {
     /// <summary>The JSON Schema generator settings.</summary>
-    public class JsonSchemaGeneratorSettings
+    public class JsonSchemaGeneratorSettings : IXmlDocsSettings
     {
         private Dictionary<string, JsonContract> _cachedContracts = new Dictionary<string, JsonContract>();
 
@@ -54,6 +54,9 @@ public JsonSchemaGeneratorSettings()
             ReflectionService = new DefaultReflectionService();
 
             ExcludedTypeNames = new string[0];
+
+            UseXmlDocumentation = true;
+            ResolveExternalXmlDocumentation = true;
         }
 
         /// <summary>Gets or sets the default reference type null handling when no nullability information is available (default: Null).</summary>
@@ -90,7 +93,7 @@ public JsonSchemaGeneratorSettings()
         /// <summary>Will set `additionalProperties` on all added <see cref="JsonSchema">schema definitions and references</see>(default: false).</summary>
         public bool AlwaysAllowAdditionalObjectProperties { get; set; }
 
-        /// <summary>Gets or sets a value indicating whether to generate the example property of the schemas based on the &lt;example&gt; xml docs entry as JSON.</summary>
+        /// <summary>Gets or sets a value indicating whether to generate the example property of the schemas based on the &lt;example&gt; xml docs entry as JSON (requires <see cref="UseXmlDocumentation"/> to be true, default: true).</summary>
         public bool GenerateExamples { get; set; }
 
         /// <summary>Gets or sets the schema type to generate (default: JsonSchema).</summary>
@@ -123,6 +126,12 @@ public object SerializerOptions
         /// <summary>Gets or sets the excluded type names (same as <see cref="JsonSchemaIgnoreAttribute"/>).</summary>
         public string[] ExcludedTypeNames { get; set; }
 
+        /// <summary>Gets or sets a value indicating whether to read XML Docs (default: true).</summary>
+        public bool UseXmlDocumentation { get; set; }
+
+        /// <summary>Gets or sets a value indicating whether tho resolve the XML Docs from the NuGet cache or .NET SDK directory (default: true).</summary>
+        public bool ResolveExternalXmlDocumentation { get; set; }
+
         /// <summary>Gets or sets the type name generator.</summary>
         [JsonIgnore]
         public ITypeNameGenerator TypeNameGenerator { get; set; }

src/NJsonSchema/Infrastructure/TypeExtensions.cs

@@ -8,6 +8,7 @@
 
 using Namotion.Reflection;
 using Newtonsoft.Json;
+using NJsonSchema.Generation;
 using System;
 using System.Collections.Generic;
 using System.Runtime.Serialization;
@@ -59,8 +60,9 @@ private static string GetNameWithoutCache(ContextualAccessorInfo accessorInfo)
 
         /// <summary>Gets the description of the given member (based on the DescriptionAttribute, DisplayAttribute or XML Documentation).</summary>
         /// <param name="type">The member info</param>
+        /// <param name="xmlDocsSettings">The XML Docs settings.</param>
         /// <returns>The description or null if no description is available.</returns>
-        public static string GetDescription(this CachedType type)
+        public static string GetDescription(this CachedType type, IXmlDocsSettings xmlDocsSettings)
         {
             var attributes = type is ContextualType contextualType ? contextualType.ContextAttributes : type.InheritedAttributes;
 
@@ -70,50 +72,61 @@ public static string GetDescription(this CachedType type)
                 return description;
             }
 
-            var summary = type.GetXmlDocsSummary();
-            if (summary != string.Empty)
+            if (xmlDocsSettings.UseXmlDocumentation)
             {
-                return summary;
+                var summary = type.GetXmlDocsSummary(xmlDocsSettings.ResolveExternalXmlDocumentation);
+                if (summary != string.Empty)
+                {
+                    return summary;
+                }
             }
 
             return null;
         }
 
         /// <summary>Gets the description of the given member (based on the DescriptionAttribute, DisplayAttribute or XML Documentation).</summary>
         /// <param name="accessorInfo">The accessor info.</param>
+        /// <param name="xmlDocsSettings">The XML Docs settings.</param>
         /// <returns>The description or null if no description is available.</returns>
-        public static string GetDescription(this ContextualAccessorInfo accessorInfo)
+        public static string GetDescription(this ContextualAccessorInfo accessorInfo, IXmlDocsSettings xmlDocsSettings)
         {
             var description = GetDescription(accessorInfo.AccessorType.Attributes);
             if (description != null)
             {
                 return description;
             }
 
-            var summary = accessorInfo.MemberInfo.GetXmlDocsSummary();
-            if (summary != string.Empty)
+            if (xmlDocsSettings.UseXmlDocumentation)
             {
-                return summary;
+                var summary = accessorInfo.MemberInfo.GetXmlDocsSummary(xmlDocsSettings.ResolveExternalXmlDocumentation);
+                if (summary != string.Empty)
+                {
+                    return summary;
+                }
             }
 
             return null;
         }
 
         /// <summary>Gets the description of the given member (based on the DescriptionAttribute, DisplayAttribute or XML Documentation).</summary>
         /// <param name="parameter">The parameter.</param>
+        /// <param name="xmlDocsSettings">The XML Docs settings.</param>
         /// <returns>The description or null if no description is available.</returns>
-        public static string GetDescription(this ContextualParameterInfo parameter)
+        public static string GetDescription(this ContextualParameterInfo parameter, IXmlDocsSettings xmlDocsSettings)
         {
             var description = GetDescription(parameter.ContextAttributes);
             if (description != null)
             {
                 return description;
             }
 
-            var summary = parameter.GetXmlDocs();
-            if (summary != string.Empty)
+            if (xmlDocsSettings.UseXmlDocumentation)
             {
-                return summary;
+                var summary = parameter.GetXmlDocs(xmlDocsSettings.ResolveExternalXmlDocumentation);
+                if (summary != string.Empty)
+                {
+                    return summary;
+                }
             }
 
             return null;

src/NJsonSchema/NJsonSchema.csproj

@@ -13,7 +13,7 @@
     <WarningsAsErrors />
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="Namotion.Reflection" Version="2.0.7" />
+    <PackageReference Include="Namotion.Reflection" Version="2.0.8" />
     <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
   </ItemGroup>
   <ItemGroup Condition="'$(TargetFramework)' == 'net40'">