Add Description to ProducesResponseType (and others) for better OpenAPI document creation

src/Http/Http.Abstractions/src/Metadata/IProducesResponseTypeMetadata.cs

@@ -18,6 +18,11 @@ public interface IProducesResponseTypeMetadata
     /// </summary>
     int StatusCode { get; }
 
+    /// <summary>
+    /// Gets the description of the response.
+    /// </summary>
+    string? Description { get; }
+
     /// <summary>
     /// Gets the content types supported by the metadata.
     /// </summary>

src/Http/Http.Abstractions/src/Metadata/ProducesResponseTypeMetadata.cs

@@ -68,6 +68,11 @@ private ProducesResponseTypeMetadata(int statusCode, Type? type, IEnumerable<str
     /// </summary>
     public int StatusCode { get; private set; }
 
+    /// <summary>
+    /// Gets or sets the description of the response.
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <summary>
     /// Gets or sets the content types associated with the response.
     /// </summary>

src/Http/Http.Abstractions/src/PublicAPI.Unshipped.txt

@@ -11,3 +11,6 @@ Microsoft.AspNetCore.Http.Metadata.IParameterBindingMetadata.HasTryParse.get ->
 Microsoft.AspNetCore.Http.Metadata.IParameterBindingMetadata.IsOptional.get -> bool
 Microsoft.AspNetCore.Http.Metadata.IParameterBindingMetadata.Name.get -> string!
 Microsoft.AspNetCore.Http.Metadata.IParameterBindingMetadata.ParameterInfo.get -> System.Reflection.ParameterInfo!
+Microsoft.AspNetCore.Http.ProducesResponseTypeMetadata.Description.get -> string?
+Microsoft.AspNetCore.Http.ProducesResponseTypeMetadata.Description.set -> void
+Microsoft.AspNetCore.Http.Metadata.IProducesResponseTypeMetadata.Description.get -> string?

src/Http/Http.Extensions/src/RequestDelegateFactory.cs

@@ -274,7 +274,7 @@ private static RequestDelegateFactoryContext CreateFactoryContext(RequestDelegat
         var serviceProvider = options?.ServiceProvider ?? options?.EndpointBuilder?.ApplicationServices ?? EmptyServiceProvider.Instance;
         var endpointBuilder = options?.EndpointBuilder ?? new RdfEndpointBuilder(serviceProvider);
         var jsonSerializerOptions = serviceProvider.GetService<IOptions<JsonOptions>>()?.Value.SerializerOptions ?? JsonOptions.DefaultSerializerOptions;
-        var formDataMapperOptions = new FormDataMapperOptions();;
+        var formDataMapperOptions = new FormDataMapperOptions();
 
         var factoryContext = new RequestDelegateFactoryContext
         {

src/Mvc/Mvc.Abstractions/src/ApiExplorer/ApiResponseType.cs

@@ -33,6 +33,11 @@ public class ApiResponseType
     /// </remarks>
     public Type? Type { get; set; }
 
+    /// <summary>
+    /// Gets or sets the description of the response.
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <summary>
     /// Gets or sets the HTTP response status code.
     /// </summary>

src/Mvc/Mvc.Abstractions/src/PublicAPI.Unshipped.txt

@@ -1 +1,3 @@
 #nullable enable
+Microsoft.AspNetCore.Mvc.ApiExplorer.ApiResponseType.Description.get -> string?
+Microsoft.AspNetCore.Mvc.ApiExplorer.ApiResponseType.Description.set -> void

src/Mvc/Mvc.Api.Analyzers/test/TestFiles/SymbolApiResponseMetadataProviderTest/GetResponseMetadataTests.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
@@ -60,6 +60,8 @@ public class CustomResponseTypeAttribute : Attribute, IApiResponseMetadataProvid
 
         public int StatusCode { get; set; }
 
+        public string Description { get; set; }
+
         public void SetContentTypes(MediaTypeCollection contentTypes)
         {
         }

src/Mvc/Mvc.ApiExplorer/src/ApiResponseTypeProvider.cs

@@ -166,11 +166,14 @@ internal static Dictionary<int, ApiResponseType> ReadResponseMetadata(
 
                 var statusCode = metadataAttribute.StatusCode;
 
+                var description = metadataAttribute.Description;
+
                 var apiResponseType = new ApiResponseType
                 {
                     Type = metadataAttribute.Type,
                     StatusCode = statusCode,
                     IsDefaultResponse = metadataAttribute is IApiDefaultResponseMetadataProvider,
+                    Description = description
                 };
 
                 if (apiResponseType.Type == typeof(void))

src/Mvc/Mvc.ApiExplorer/src/PublicAPI.Unshipped.txt

@@ -1 +1,3 @@
 #nullable enable
+Microsoft.AspNetCore.Mvc.ApiExplorer.ApiResponseType.Description.get -> string? (forwarded, contained in Microsoft.AspNetCore.Mvc.Abstractions)
+Microsoft.AspNetCore.Mvc.ApiExplorer.ApiResponseType.Description.set -> void (forwarded, contained in Microsoft.AspNetCore.Mvc.Abstractions)

src/Mvc/Mvc.ApiExplorer/test/DefaultApiDescriptionProviderTest.cs

@@ -1107,7 +1107,8 @@ public void GetApiDescription_PopulatesResponseInformation_WhenSetByFilter(strin
         var action = CreateActionDescriptor(methodName);
         var filter = new ContentTypeAttribute("text/*")
         {
-            Type = typeof(Order)
+            Type = typeof(Order),
+            Description = "Example"
         };
 
         action.FilterDescriptors = new List<FilterDescriptor>
@@ -1124,6 +1125,7 @@ public void GetApiDescription_PopulatesResponseInformation_WhenSetByFilter(strin
         Assert.NotNull(responseTypes.ModelMetadata);
         Assert.Equal(200, responseTypes.StatusCode);
         Assert.Equal(typeof(Order), responseTypes.Type);
+        Assert.Equal("Example", responseTypes.Description);
 
         foreach (var responseFormat in responseTypes.ApiResponseFormats)
         {
@@ -2874,6 +2876,8 @@ public ContentTypeAttribute(string mediaType)
 
         public Type Type { get; set; }
 
+        public string Description { get; set; }
+
         public void SetContentTypes(MediaTypeCollection contentTypes)
         {
             contentTypes.Clear();

src/Mvc/Mvc.Core/src/ApiExplorer/IApiResponseMetadataProvider.cs

@@ -17,6 +17,11 @@ public interface IApiResponseMetadataProvider : IFilterMetadata
     /// </summary>
     Type? Type { get; }
 
+    /// <summary>
+    /// Gets the description of the response.
+    /// </summary>
+    string? Description { get; }
+
     /// <summary>
     /// Gets the HTTP status code of the response.
     /// </summary>

src/Mvc/Mvc.Core/src/ProducesAttribute.cs

@@ -52,6 +52,9 @@ public ProducesAttribute(string contentType, params string[] additionalContentTy
     /// <inheritdoc />
     public Type? Type { get; set; }
 
+    /// <inheritdoc />
+    public string? Description { get; set; }
+
     /// <summary>
     /// Gets or sets the supported response content types. Used to set <see cref="ObjectResult.ContentTypes"/>.
     /// </summary>

src/Mvc/Mvc.Core/src/ProducesDefaultResponseTypeAttribute.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
@@ -39,6 +39,11 @@ public ProducesDefaultResponseTypeAttribute(Type type)
     /// </summary>
     public int StatusCode { get; }
 
+    /// <summary>
+    /// Gets or sets the description of the response.
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <inheritdoc />
     void IApiResponseMetadataProvider.SetContentTypes(MediaTypeCollection contentTypes)
     {

src/Mvc/Mvc.Core/src/ProducesResponseTypeAttribute.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
@@ -87,6 +87,11 @@ public ProducesResponseTypeAttribute(Type type, int statusCode, string contentTy
     // Internal for testing
     internal MediaTypeCollection? ContentTypes => _contentTypes;
 
+    /// <summary>
+    /// Gets or sets the description of the response.
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <inheritdoc />
     void IApiResponseMetadataProvider.SetContentTypes(MediaTypeCollection contentTypes)
     {

src/Mvc/Mvc.Core/src/PublicAPI.Unshipped.txt

@@ -1,6 +1,13 @@
 #nullable enable
 *REMOVED*virtual Microsoft.AspNetCore.Mvc.ControllerBase.Problem(string? detail = null, string? instance = null, int? statusCode = null, string? title = null, string? type = null) -> Microsoft.AspNetCore.Mvc.ObjectResult!
 *REMOVED*virtual Microsoft.AspNetCore.Mvc.ControllerBase.ValidationProblem(string? detail = null, string? instance = null, int? statusCode = null, string? title = null, string? type = null, Microsoft.AspNetCore.Mvc.ModelBinding.ModelStateDictionary? modelStateDictionary = null) -> Microsoft.AspNetCore.Mvc.ActionResult!
+Microsoft.AspNetCore.Mvc.ApiExplorer.IApiResponseMetadataProvider.Description.get -> string?
+Microsoft.AspNetCore.Mvc.ProducesAttribute.Description.get -> string?
+Microsoft.AspNetCore.Mvc.ProducesAttribute.Description.set -> void
+Microsoft.AspNetCore.Mvc.ProducesDefaultResponseTypeAttribute.Description.get -> string?
+Microsoft.AspNetCore.Mvc.ProducesDefaultResponseTypeAttribute.Description.set -> void
+Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute.Description.get -> string?
+Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute.Description.set -> void
 virtual Microsoft.AspNetCore.Mvc.ControllerBase.Problem(string? detail, string? instance, int? statusCode, string? title, string? type) -> Microsoft.AspNetCore.Mvc.ObjectResult!
 virtual Microsoft.AspNetCore.Mvc.ControllerBase.Problem(string? detail = null, string? instance = null, int? statusCode = null, string? title = null, string? type = null, System.Collections.Generic.IDictionary<string!, object?>? extensions = null) -> Microsoft.AspNetCore.Mvc.ObjectResult!
 virtual Microsoft.AspNetCore.Mvc.ControllerBase.ValidationProblem(string? detail, string? instance, int? statusCode, string? title, string? type, Microsoft.AspNetCore.Mvc.ModelBinding.ModelStateDictionary? modelStateDictionary) -> Microsoft.AspNetCore.Mvc.ActionResult!

src/Mvc/Mvc.Core/test/ProducesAttributeTests.cs

@@ -151,6 +151,29 @@ public void ProducesAttribute_WithTypeOnly_DoesNotSetContentTypes()
         Assert.Empty(producesAttribute.ContentTypes);
     }
 
+    [Fact]
+    public void ProducesAttribute_SetsDescription()
+    {
+        // Arrange
+        var producesAttribute = new ProducesAttribute(typeof(Person))
+        {
+            Description = "Example"
+        };
+
+        // Act and Assert
+        Assert.Equal("Example", producesAttribute.Description);
+    }
+
+    [Fact]
+    public void ProducesAttribute_WithTypeOnly_DoesNotSetDescription()
+    {
+        // Arrange
+        var producesAttribute = new ProducesAttribute(typeof(Person));
+
+        // Act and Assert
+        Assert.Null(producesAttribute.Description);
+    }
+
     private static ResultExecutedContext CreateResultExecutedContext(ResultExecutingContext context)
     {
         return new ResultExecutedContext(context, context.Filters, context.Result, context.Controller);

src/Mvc/Mvc.Core/test/ProducesResponseTypeAttributeTests.cs

@@ -67,6 +67,29 @@ public void ProducesResponseTypeAttribute_WithTypeOnly_DoesNotSetContentTypes()
         Assert.Null(producesResponseTypeAttribute.ContentTypes);
     }
 
+    [Fact]
+    public void ProducesResponseTypeAttribute_SetsDescription()
+    {
+        // Arrange
+        var producesResponseTypeAttribute = new ProducesResponseTypeAttribute(typeof(Person), StatusCodes.Status200OK)
+        {
+            Description = "Example"
+        };
+
+        // Act and Assert
+        Assert.Equal("Example", producesResponseTypeAttribute.Description);
+    }
+
+    [Fact]
+    public void ProducesResponseTypeAttribute_WithTypeOnly_DoesNotSetDescription()
+    {
+        // Arrange
+        var producesResponseTypeAttribute = new ProducesResponseTypeAttribute(typeof(Person), StatusCodes.Status200OK);
+
+        // Act and Assert
+        Assert.Null(producesResponseTypeAttribute.Description);
+    }
+
     private class Person
     {
         public int Id { get; set; }