Favor parameter.description over parameter.schema.description

domaindrivendev · Feb 22, 2021 · 79b13b7 · 79b13b7
1 parent d88a5df
commit 79b13b7
Show file tree

Hide file tree

Showing 3 changed files with 6 additions and 6 deletions.
diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsParameterFilter.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsParameterFilter.cs
@@ -34,7 +34,10 @@ private void ApplyPropertyTags(OpenApiParameter parameter, ParameterFilterContex
 
             var summaryNode = propertyNode.SelectSingleNode("summary");
             if (summaryNode != null)
+            {
                 parameter.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
+                parameter.Schema.Description = null; // no need to duplicate
+            }
 
             var exampleNode = propertyNode.SelectSingleNode("example");
             if (exampleNode != null)

diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs
@@ -17,11 +17,7 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
         {
             ApplyTypeTags(schema, context.Type);
 
-            // If it's for a C# field/property and it's NOT bound to a request parameter (e.g. via [FromRoute], [FromQuery] etc.),
-            // then the field/property tags can be applied here. If it is bound to a request parameter, the field/property tags
-            // will be applied a level up on the corresponding OpenApiParameter (see XmlCommentsParameterFilter).
-
-            if (context.MemberInfo != null && context.ParameterInfo == null)
+            if (context.MemberInfo != null)
             {
                 ApplyMemberTags(schema, context);
             }

diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsParameterFilterTests.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsParameterFilterTests.cs
@@ -46,14 +46,15 @@ public void Apply_SetsDescriptionAndExample_FromUnderlyingGenericTypeActionParam
         [Fact]
         public void Apply_SetsDescriptionAndExample_FromPropertySummaryAndExampleTags()
         {
-            var parameter = new OpenApiParameter { Schema = new OpenApiSchema { Type = "string" } };
+            var parameter = new OpenApiParameter { Schema = new OpenApiSchema { Type = "string", Description = "schema-level description" } };
             var propertyInfo = typeof(XmlAnnotatedType).GetProperty(nameof(XmlAnnotatedType.StringProperty));
             var apiParameterDescription = new ApiParameterDescription { };
             var filterContext = new ParameterFilterContext(apiParameterDescription, null, null, propertyInfo: propertyInfo);
 
             Subject().Apply(parameter, filterContext);
 
             Assert.Equal("Summary for StringProperty", parameter.Description);
+            Assert.Null(parameter.Schema.Description);
             Assert.NotNull(parameter.Example);
             Assert.Equal("\"Example for StringProperty\"", parameter.Example.ToJson());
         }