Add support for WithSummary and WithDescription metadata (domaindrive…

…ndev#2414) Adds a default summary value to OpenApiOperation's derived from an `IEndpointSummaryMetadata` on the API action.
jcracknell · Apr 15, 2024 · 102fccf · 102fccf
1 parent eeb0940
commit 102fccf
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 5 deletions.
diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs
@@ -10,6 +10,9 @@
 using Microsoft.AspNetCore.Mvc.ModelBinding;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.Swagger;
+#if NET7_0_OR_GREATER
+using Microsoft.AspNetCore.Http.Metadata;
+#endif
 
 namespace Swashbuckle.AspNetCore.SwaggerGen
 {
@@ -212,7 +215,11 @@ private OpenApiOperation GenerateOperation(ApiDescription apiDescription, Schema
                     Parameters = GenerateParameters(apiDescription, schemaRepository),
                     RequestBody = GenerateRequestBody(apiDescription, schemaRepository),
                     Responses = GenerateResponses(apiDescription, schemaRepository),
-                    Deprecated = apiDescription.CustomAttributes().OfType<ObsoleteAttribute>().Any()
+                    Deprecated = apiDescription.CustomAttributes().OfType<ObsoleteAttribute>().Any(),
+#if NET7_0_OR_GREATER
+                    Summary = GenerateSummary(apiDescription),
+                    Description = GenerateDescription(apiDescription),
+#endif
                 };
 
                 apiDescription.TryGetMethodInfo(out MethodInfo methodInfo);
@@ -650,5 +657,19 @@ private OpenApiMediaType CreateResponseMediaType(ModelMetadata modelMetadata, Sc
             new KeyValuePair<string, string>("5\\d{2}", "Server Error"),
             new KeyValuePair<string, string>("default", "Error")
         };
+
+#if NET7_0_OR_GREATER
+        private string GenerateSummary(ApiDescription apiDescription) =>
+            apiDescription.ActionDescriptor?.EndpointMetadata
+                ?.OfType<IEndpointSummaryMetadata>()
+                .Select(s => s.Summary)
+                .LastOrDefault();
+
+        private string GenerateDescription(ApiDescription apiDescription) =>
+            apiDescription.ActionDescriptor?.EndpointMetadata
+                ?.OfType<IEndpointDescriptionMetadata>()
+                .Select(s => s.Description)
+                .LastOrDefault();
+#endif
     }
 }
diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/SwaggerGenerator/SwaggerGeneratorTests.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/SwaggerGenerator/SwaggerGeneratorTests.cs
@@ -151,8 +151,8 @@ public void GetSwagger_UseProvidedOpenApiOperation_IfExistsInMetadata()
             var actionDescriptor = new ActionDescriptor
             {
                 EndpointMetadata = new List<object>()
-                { 
-                    new OpenApiOperation 
+                {
+                    new OpenApiOperation
                     {
                         OperationId = "OperationIdSetInMetadata",
                         Parameters = new List<OpenApiParameter>()
@@ -199,7 +199,7 @@ public void GetSwagger_GenerateProducesSchemas_ForProvidedOpenApiOperation()
                             {
                                 Content = new Dictionary<string, OpenApiMediaType>()
                                 {
-                                    ["application/someMediaType"] = new() 
+                                    ["application/someMediaType"] = new()
                                 }
                             }
                         }
@@ -965,6 +965,56 @@ public void GetSwagger_CanReadTagsFromMetadata()
             Assert.Equal(new[] { "Some", "Tags", "Here" }, document.Paths["/resource"].Operations[OperationType.Post].Tags.Select(t => t.Name));
         }
 
+#if NET7_0_OR_GREATER
+        [Fact]
+        public void GetSwagger_CanReadEndpointSummaryFromMetadata()
+        {
+            var methodInfo = typeof(FakeController).GetMethod(nameof(FakeController.ActionWithParameter));
+            var actionDescriptor = new ActionDescriptor
+            {
+                EndpointMetadata = new List<object>() { new EndpointSummaryAttribute("A Test Summary") },
+                RouteValues = new Dictionary<string, string>
+                {
+                    ["controller"] = methodInfo.DeclaringType.Name.Replace("Controller", string.Empty)
+                }
+            };
+            var subject = Subject(
+                apiDescriptions: new[]
+                {
+                    ApiDescriptionFactory.Create(actionDescriptor, methodInfo, groupName: "v1", httpMethod: "POST", relativePath: "resource"),
+                }
+            );
+
+            var document = subject.GetSwagger("v1");
+
+            Assert.Equal("A Test Summary", document.Paths["/resource"].Operations[OperationType.Post].Summary);
+        }
+
+        [Fact]
+        public void GetSwagger_CanReadEndpointDescriptionFromMetadata()
+        {
+            var methodInfo = typeof(FakeController).GetMethod(nameof(FakeController.ActionWithParameter));
+            var actionDescriptor = new ActionDescriptor
+            {
+                EndpointMetadata = new List<object>() { new EndpointDescriptionAttribute("A Test Description") },
+                RouteValues = new Dictionary<string, string>
+                {
+                    ["controller"] = methodInfo.DeclaringType.Name.Replace("Controller", string.Empty)
+                }
+            };
+            var subject = Subject(
+                apiDescriptions: new[]
+                {
+                    ApiDescriptionFactory.Create(actionDescriptor, methodInfo, groupName: "v1", httpMethod: "POST", relativePath: "resource"),
+                }
+            );
+
+            var document = subject.GetSwagger("v1");
+
+            Assert.Equal("A Test Description", document.Paths["/resource"].Operations[OperationType.Post].Description);
+        }
+#endif
+
         [Fact]
         public void GetSwagger_SupportsOption_ConflictingActionsResolver()
         {

diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/Swashbuckle.AspNetCore.SwaggerGen.Test.csproj b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/Swashbuckle.AspNetCore.SwaggerGen.Test.csproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <NoWarn>1701;1702;1591</NoWarn>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
   </PropertyGroup>
 
   <ItemGroup>