Use xml docs settings

RicoSuter · Dec 9, 2021 · 805fc28 · 805fc28
1 parent e7940cd
commit 805fc28
Show file tree

Hide file tree

Showing 7 changed files with 26 additions and 17 deletions.
diff --git a/src/NSwag.Generation.AspNetCore/Processors/AspNetCoreOperationTagsProcessor.cs b/src/NSwag.Generation.AspNetCore/Processors/AspNetCoreOperationTagsProcessor.cs
@@ -48,8 +48,9 @@ protected override void AddControllerNameTag(OperationProcessorContext context)
             var aspNetCoreContext = (AspNetCoreOperationProcessorContext)context;
             if (aspNetCoreContext.ApiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor)
             {
+                var summary = controllerActionDescriptor.ControllerTypeInfo.GetXmlDocsSummary(context.Settings.ResolveExternalXmlDocumentation);
                 aspNetCoreContext.OperationDescription.Operation.Tags.Add(controllerActionDescriptor.ControllerName);
-                UpdateDocumentTagDescription(context, controllerActionDescriptor.ControllerName, controllerActionDescriptor.ControllerTypeInfo.GetXmlDocsSummary());
+                UpdateDocumentTagDescription(context, controllerActionDescriptor.ControllerName, summary);
             }
             else
             {

diff --git a/src/NSwag.Generation.AspNetCore/Processors/OperationParameterProcessor.cs b/src/NSwag.Generation.AspNetCore/Processors/OperationParameterProcessor.cs
@@ -65,7 +65,7 @@ public bool Process(OperationProcessorContext operationProcessorContext)
                 // value that's different than the parameter name. Additionally, ApiExplorer will recurse in to complex model bound types
                 // and expose properties as top level parameters. Consequently, determining the property or parameter of an Api is best
                 // effort attempt.
-                var extendedApiParameter = new ExtendedApiParameterDescription
+                var extendedApiParameter = new ExtendedApiParameterDescription(_settings)
                 {
                     ApiParameter = apiParameter,
                     Attributes = Enumerable.Empty<Attribute>(),
@@ -495,6 +495,8 @@ private OpenApiParameter CreatePrimitiveParameter(
 
         private class ExtendedApiParameterDescription
         {
+            private readonly IXmlDocsSettings _xmlDocsSettings;
+
             public ApiParameterDescription ApiParameter { get; set; }
 
             public ParameterInfo ParameterInfo { get; set; }
@@ -505,6 +507,11 @@ private class ExtendedApiParameterDescription
 
             public IEnumerable<Attribute> Attributes { get; set; } = Enumerable.Empty<Attribute>();
 
+            public ExtendedApiParameterDescription(IXmlDocsSettings xmlDocsSettings)
+            {
+                _xmlDocsSettings = xmlDocsSettings;
+            }
+
             public bool IsRequired(bool requireParametersWithoutDefault)
             {
                 var isRequired = false;
@@ -543,11 +550,11 @@ public string GetDocumentation()
                 var parameterDocumentation = string.Empty;
                 if (ParameterInfo != null)
                 {
-                    parameterDocumentation = ParameterInfo.ToContextualParameter().GetDescription();
+                    parameterDocumentation = ParameterInfo.ToContextualParameter().GetDescription(_xmlDocsSettings);
                 }
                 else if (PropertyInfo != null)
                 {
-                    parameterDocumentation = PropertyInfo.ToContextualProperty().GetDescription();
+                    parameterDocumentation = PropertyInfo.ToContextualProperty().GetDescription(_xmlDocsSettings);
                 }
 
                 return parameterDocumentation;

diff --git a/src/NSwag.Generation.WebApi/Processors/OperationParameterProcessor.cs b/src/NSwag.Generation.WebApi/Processors/OperationParameterProcessor.cs
@@ -320,7 +320,7 @@ private OpenApiParameter TryAddFileParameter(
         private OpenApiParameter AddFileParameter(OperationProcessorContext context, ContextualParameterInfo contextualParameter, bool isFileArray)
         {
             // TODO: Check if there is a way to control the property name
-            var parameterDocumentation = contextualParameter.GetDescription();
+            var parameterDocumentation = contextualParameter.GetDescription(_settings);
             var operationParameter = context.DocumentGenerator.CreatePrimitiveParameter(
                 contextualParameter.Name, parameterDocumentation, contextualParameter);
 
@@ -373,7 +373,7 @@ private OpenApiParameter AddBodyParameter(OperationProcessorContext context, str
                     },
                     IsNullableRaw = isNullable,
                     IsRequired = isRequired,
-                    Description = contextualParameter.GetDescription()
+                    Description = contextualParameter.GetDescription(_settings)
                 };
                 operation.Parameters.Add(operationParameter);
             }
@@ -392,7 +392,7 @@ private OpenApiParameter AddBodyParameter(OperationProcessorContext context, str
                     },
                     IsNullableRaw = isNullable,
                     IsRequired = isRequired,
-                    Description = contextualParameter.GetDescription()
+                    Description = contextualParameter.GetDescription(_settings)
                 };
                 operation.Parameters.Add(operationParameter);
             }
@@ -404,7 +404,7 @@ private OpenApiParameter AddBodyParameter(OperationProcessorContext context, str
                     Kind = OpenApiParameterKind.Body,
                     IsRequired = isRequired,
                     IsNullableRaw = isNullable,
-                    Description = contextualParameter.GetDescription(),
+                    Description = contextualParameter.GetDescription(_settings),
                     Schema = context.SchemaGenerator.GenerateWithReferenceAndNullability<JsonSchema>(
                         contextualParameter, isNullable, schemaResolver: context.SchemaResolver)
                 };
@@ -421,7 +421,7 @@ private OpenApiParameter AddPrimitiveParametersFromUri(
 
             if (typeDescription.Type.HasFlag(JsonObjectType.Array))
             {
-                var parameterDocumentation = contextualParameter.GetDescription();
+                var parameterDocumentation = contextualParameter.GetDescription(_settings);
                 var operationParameter = context.DocumentGenerator.CreatePrimitiveParameter(
                     name, parameterDocumentation, contextualParameter);
 
@@ -453,7 +453,7 @@ private OpenApiParameter AddPrimitiveParametersFromUri(
                             propertyName = fromHeaderAttribute?.Name;
                         }
 
-                        var propertySummary = contextualProperty.PropertyInfo.GetXmlDocsSummary();
+                        var propertySummary = contextualProperty.PropertyInfo.GetXmlDocsSummary(_settings.ResolveExternalXmlDocumentation);
                         var operationParameter = context.DocumentGenerator.CreatePrimitiveParameter(propertyName, propertySummary, contextualProperty.AccessorType);
 
                         // TODO: Check if required can be controlled with mechanisms other than RequiredAttribute

diff --git a/src/NSwag.Generation/OpenApiDocumentGenerator.cs b/src/NSwag.Generation/OpenApiDocumentGenerator.cs
@@ -72,7 +72,7 @@ public OpenApiParameter CreateUntypedPathParameter(string parameterName, string
         /// <returns>The parameter.</returns>
         public OpenApiParameter CreatePrimitiveParameter(string name, ContextualParameterInfo contextualParameter)
         {
-            var documentation = contextualParameter.GetDescription();
+            var documentation = contextualParameter.GetDescription(_settings);
             return CreatePrimitiveParameter(name, documentation, contextualParameter);
         }
 

diff --git a/src/NSwag.Generation/Processors/OperationResponseProcessorBase.cs b/src/NSwag.Generation/Processors/OperationResponseProcessorBase.cs
@@ -45,7 +45,7 @@ public void ProcessResponseTypeAttributes(OperationProcessorContext operationPro
 
             var successResponseDescription = returnParameter
                 .ToContextualParameter()
-                .GetDescription() ?? string.Empty;
+                .GetDescription(_settings) ?? string.Empty;
 
             var responseDescriptions = GetOperationResponseDescriptions(responseTypeAttributes, successResponseDescription);
             ProcessOperationDescriptions(responseDescriptions, returnParameter, operationProcessorContext, successResponseDescription);
@@ -63,7 +63,7 @@ protected void UpdateResponseDescription(OperationProcessorContext operationProc
 
             var returnParameter = operationProcessorContext.MethodInfo.ReturnParameter.ToContextualParameter();
 
-            var returnParameterXmlDocs = returnParameter.GetDescription() ?? string.Empty;
+            var returnParameterXmlDocs = returnParameter.GetDescription(_settings) ?? string.Empty;
             var operationXmlDocsNodes = GetResponseXmlDocsNodes(operationProcessorContext.MethodInfo);
 
             if (!string.IsNullOrEmpty(returnParameterXmlDocs) || operationXmlDocsNodes?.Any() == true)
@@ -99,7 +99,7 @@ protected XElement GetResponseXmlDocsElement(MethodInfo methodInfo, string respo
 
         private IEnumerable<XElement> GetResponseXmlDocsNodes(MethodInfo methodInfo)
         {
-            var operationXmlDocs = methodInfo?.GetXmlDocsElement();
+            var operationXmlDocs = methodInfo?.GetXmlDocsElement(_settings.ResolveExternalXmlDocumentation);
             return operationXmlDocs?.Nodes()?.OfType<XElement>();
         }
 

diff --git a/src/NSwag.Generation/Processors/OperationSummaryAndDescriptionProcessor.cs b/src/NSwag.Generation/Processors/OperationSummaryAndDescriptionProcessor.cs
@@ -48,7 +48,7 @@ private void ProcessSummary(OperationProcessorContext context, Attribute[] attri
 
             if (string.IsNullOrEmpty(summary))
             {
-                summary = context.MethodInfo?.GetXmlDocsSummary();
+                summary = context.MethodInfo?.GetXmlDocsSummary(context.Settings.ResolveExternalXmlDocumentation);
             }
 
             if (!string.IsNullOrEmpty(summary))
@@ -66,7 +66,7 @@ private void ProcessDescription(OperationProcessorContext context, Attribute[] a
 
             if (string.IsNullOrEmpty(description))
             {
-                description = context.MethodInfo?.GetXmlDocsRemarks();
+                description = context.MethodInfo?.GetXmlDocsRemarks(context.Settings.ResolveExternalXmlDocumentation);
             }
 
             if (!string.IsNullOrEmpty(description))

diff --git a/src/NSwag.Generation/Processors/OperationTagsProcessor.cs b/src/NSwag.Generation/Processors/OperationTagsProcessor.cs
@@ -58,8 +58,9 @@ protected virtual void AddControllerNameTag(OperationProcessorContext context)
                 controllerName = controllerName.Substring(0, controllerName.Length - 10);
             }
 
+            var summary = context.ControllerType.GetXmlDocsSummary(context.Settings.ResolveExternalXmlDocumentation);
             context.OperationDescription.Operation.Tags.Add(controllerName);
-            UpdateDocumentTagDescription(context, controllerName, context.ControllerType.GetXmlDocsSummary());
+            UpdateDocumentTagDescription(context, controllerName, summary);
         }
 
         /// <summary>