Add Description to OpenApiRouteHandlerBuilderExtensions and extra constructor and static methods to ProducesResponseTypeMetadata for correct description overloads

sander1095 · sander1095 · commit 442d101b3f26 · 2024-08-16T15:45:57.000+02:00
diff --git a/src/Http/Http.Abstractions/src/Metadata/ProducesResponseTypeMetadata.cs b/src/Http/Http.Abstractions/src/Metadata/ProducesResponseTypeMetadata.cs
@@ -50,6 +50,43 @@ static void ValidateContentType(string type)
         }
     }
 
+    /// <summary>
+    /// Initializes an instance of <see cref="ProducesResponseTypeMetadata"/>.
+    /// </summary>
+    /// <param name="statusCode">The HTTP response status code.</param>
+    /// <param name="type">The <see cref="Type"/> of object that is going to be written in the response.</param>
+    /// <param name="description">The descrption of the response.</param>
+    /// <param name="contentTypes">Content types supported by the response.</param>
+    public ProducesResponseTypeMetadata(int statusCode, Type? type = null, string? description = null, string[]? contentTypes = null)
+    {
+        StatusCode = statusCode;
+        Type = type;
+        Description = description;
+
+        if (contentTypes is null || contentTypes.Length == 0)
+        {
+            ContentTypes = Enumerable.Empty<string>();
+        }
+        else
+        {
+            for (var i = 0; i < contentTypes.Length; i++)
+            {
+                MediaTypeHeaderValue.Parse(contentTypes[i]);
+                ValidateContentType(contentTypes[i]);
+            }
+
+            ContentTypes = contentTypes;
+        }
+
+        static void ValidateContentType(string type)
+        {
+            if (type.Contains('*', StringComparison.OrdinalIgnoreCase))
+            {
+                throw new InvalidOperationException($"Could not parse '{type}'. Content types with wildcards are not supported.");
+            }
+        }
+    }
+
     // Only for internal use where validation is unnecessary.
     private ProducesResponseTypeMetadata(int statusCode, Type? type, IEnumerable<string> contentTypes)
     {
@@ -58,6 +95,15 @@ private ProducesResponseTypeMetadata(int statusCode, Type? type, IEnumerable<str
         ContentTypes = contentTypes;
     }
 
+    // Only for internal use where validation is unnecessary.
+    private ProducesResponseTypeMetadata(int statusCode, Type? type, string? description, IEnumerable<string> contentTypes)
+    {
+        Type = type;
+        StatusCode = statusCode;
+        Description = description;
+        ContentTypes = contentTypes;
+    }
+
     /// <summary>
     /// Gets or sets the type of the value returned by an action.
     /// </summary>
@@ -81,8 +127,9 @@ private ProducesResponseTypeMetadata(int statusCode, Type? type, IEnumerable<str
     /// <inheritdoc/>
     public override string ToString()
     {
-        return DebuggerHelpers.GetDebugText(nameof(StatusCode), StatusCode, nameof(ContentTypes), ContentTypes, nameof(Type), Type, includeNullValues: false, prefix: "Produces");
+        return DebuggerHelpers.GetDebugText(nameof(StatusCode), StatusCode, nameof(ContentTypes), ContentTypes, nameof(Type), Type, nameof(Description), Description, includeNullValues: false, prefix: "Produces");
     }
 
     internal static ProducesResponseTypeMetadata CreateUnvalidated(Type? type, int statusCode, IEnumerable<string> contentTypes) => new(statusCode, type, contentTypes);
+    internal static ProducesResponseTypeMetadata CreateUnvalidated(Type? type, int statusCode, string? description, IEnumerable<string> contentTypes) => new(statusCode, type, description, contentTypes);
 }
diff --git a/src/Http/Routing/src/Builder/OpenApiRouteHandlerBuilderExtensions.cs b/src/Http/Routing/src/Builder/OpenApiRouteHandlerBuilderExtensions.cs
@@ -55,6 +55,29 @@ public static RouteHandlerBuilder Produces<TResponse>(
         return Produces(builder, statusCode, typeof(TResponse), contentType, additionalContentTypes);
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> to <see cref="EndpointBuilder.Metadata"/> for all endpoints
+    /// produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <typeparam name="TResponse">The type of the response.</typeparam>
+    /// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
+    /// <param name="statusCode">The response status code. Defaults to <see cref="StatusCodes.Status200OK"/>.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/json".</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="additionalContentTypes">Additional response content types the endpoint produces for the supplied status code.</param>
+    /// <returns>A <see cref="RouteHandlerBuilder"/> that can be used to further customize the endpoint.</returns>
+#pragma warning disable RS0026
+    public static RouteHandlerBuilder Produces<TResponse>(
+#pragma warning restore RS0026
+        this RouteHandlerBuilder builder,
+        int statusCode = StatusCodes.Status200OK,
+        string? contentType = null,
+        string? description = null,
+        params string[] additionalContentTypes)
+    {
+        return Produces(builder, statusCode, typeof(TResponse), contentType, description, additionalContentTypes);
+    }
+
     /// <summary>
     /// Adds an <see cref="IProducesResponseTypeMetadata"/> to <see cref="EndpointBuilder.Metadata"/> for all endpoints
     /// produced by <paramref name="builder"/>.
@@ -91,6 +114,44 @@ public static RouteHandlerBuilder Produces(
         return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, responseType ?? typeof(void), contentTypes));
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> to <see cref="EndpointBuilder.Metadata"/> for all endpoints
+    /// produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
+    /// <param name="statusCode">The response status code.</param>
+    /// <param name="responseType">The type of the response. Defaults to null.</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/json" if responseType is not null, otherwise defaults to null.</param>
+    /// <param name="additionalContentTypes">Additional response content types the endpoint produces for the supplied status code.</param>
+    /// <returns>A <see cref="RouteHandlerBuilder"/> that can be used to further customize the endpoint.</returns>
+#pragma warning disable RS0026
+    public static RouteHandlerBuilder Produces(
+#pragma warning restore RS0026
+        this RouteHandlerBuilder builder,
+        int statusCode,
+        Type? responseType = null,
+        string? description = null,
+        string? contentType = null,
+        params string[] additionalContentTypes)
+    {
+        if (responseType is Type && string.IsNullOrEmpty(contentType))
+        {
+            contentType = ContentTypeConstants.JsonContentType;
+        }
+
+        if (contentType is null)
+        {
+            return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, responseType ?? typeof(void), description));
+        }
+
+        var contentTypes = new string[additionalContentTypes.Length + 1];
+        contentTypes[0] = contentType;
+        additionalContentTypes.CopyTo(contentTypes, 1);
+
+        return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, responseType ?? typeof(void), description, contentTypes));
+    }
+
     /// <summary>
     /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="ProblemDetails"/> type
     /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
@@ -109,6 +170,25 @@ public static RouteHandlerBuilder ProducesProblem(this RouteHandlerBuilder build
         return Produces(builder, statusCode, typeof(ProblemDetails), contentType);
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="ProblemDetails"/> type
+    /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
+    /// <param name="statusCode">The response status code.</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/problem+json".</param>
+    /// <returns>A <see cref="RouteHandlerBuilder"/> that can be used to further customize the endpoint.</returns>
+    public static RouteHandlerBuilder ProducesProblem(this RouteHandlerBuilder builder, int statusCode, string? description = null, string? contentType = null)
+    {
+        if (string.IsNullOrEmpty(contentType))
+        {
+            contentType = ContentTypeConstants.ProblemDetailsContentType;
+        }
+
+        return Produces(builder, statusCode, typeof(ProblemDetails), description, contentType);
+    }
+
     /// <summary>
     /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="ProblemDetails"/> type
     /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
@@ -130,6 +210,28 @@ public static TBuilder ProducesProblem<TBuilder>(this TBuilder builder, int stat
         return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, typeof(ProblemDetails), [contentType]));
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="ProblemDetails"/> type
+    /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
+    /// <param name="statusCode">The response status code.</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/problem+json".</param>
+    /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static TBuilder ProducesProblem<TBuilder>(this TBuilder builder, int statusCode, string? description = null, string? contentType = null)
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        where TBuilder : IEndpointConventionBuilder
+    {
+        if (string.IsNullOrEmpty(contentType))
+        {
+            contentType = ContentTypeConstants.ProblemDetailsContentType;
+        }
+
+        return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, typeof(ProblemDetails), description, [contentType]));
+    }
+
     /// <summary>
     /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="HttpValidationProblemDetails"/> type
     /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
@@ -151,6 +253,29 @@ public static RouteHandlerBuilder ProducesValidationProblem(
         return Produces(builder, statusCode, typeof(HttpValidationProblemDetails), contentType);
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="HttpValidationProblemDetails"/> type
+    /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
+    /// <param name="statusCode">The response status code. Defaults to <see cref="StatusCodes.Status400BadRequest"/>.</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/problem+json".</param>
+    /// <returns>A <see cref="RouteHandlerBuilder"/> that can be used to further customize the endpoint.</returns>
+    public static RouteHandlerBuilder ProducesValidationProblem(
+        this RouteHandlerBuilder builder,
+        int statusCode = StatusCodes.Status400BadRequest,
+        string? description = null,
+        string? contentType = null)
+    {
+        if (string.IsNullOrEmpty(contentType))
+        {
+            contentType = ContentTypeConstants.ProblemDetailsContentType;
+        }
+
+        return Produces(builder, statusCode, typeof(HttpValidationProblemDetails), description, contentType);
+    }
+
     /// <summary>
     /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="HttpValidationProblemDetails"/> type
     /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
@@ -175,6 +300,32 @@ public static TBuilder ProducesValidationProblem<TBuilder>(
         return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, typeof(HttpValidationProblemDetails), [contentType]));
     }
 
+    /// <summary>
+    /// Adds an <see cref="IProducesResponseTypeMetadata"/> with a <see cref="HttpValidationProblemDetails"/> type
+    /// to <see cref="EndpointBuilder.Metadata"/> for all endpoints produced by <paramref name="builder"/>.
+    /// </summary>
+    /// <param name="builder">The <see cref="IEndpointConventionBuilder"/>.</param>
+    /// <param name="statusCode">The response status code. Defaults to <see cref="StatusCodes.Status400BadRequest"/>.</param>
+    /// <param name="description">The description of the response. Defaults to null.</param>
+    /// <param name="contentType">The response content type. Defaults to "application/problem+json".</param>
+    /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static TBuilder ProducesValidationProblem<TBuilder>(
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        this TBuilder builder,
+        int statusCode = StatusCodes.Status400BadRequest,
+        string? description = null,
+        string? contentType = null)
+        where TBuilder : IEndpointConventionBuilder
+    {
+        if (string.IsNullOrEmpty(contentType))
+        {
+            contentType = ContentTypeConstants.ProblemDetailsContentType;
+        }
+
+        return builder.WithMetadata(new ProducesResponseTypeMetadata(statusCode, typeof(HttpValidationProblemDetails), description, [contentType]));
+    }
+
     /// <summary>
     /// Adds the <see cref="ITagsMetadata"/> to <see cref="EndpointBuilder.Metadata"/> for all endpoints
     /// produced by <paramref name="builder"/>.
