Melhorias de Documentação e Funcionalidade

* Atualizações de Versão e Documentação
  - Atualizado `SPPreview` para `-preview-4.8` em `Directory.Build.props`.
  - Documentação XML detalhada adicionada à classe `ResponseTypeMetadata`.

* Melhorias em Atributos e Métodos
  - Adicionado `using System.Reflection;` em `ProduceProblemsAttribute.cs`.
  - Estendido `ProduceProblemsAttribute` com novas propriedades e construtores.
  - Modificado `GetStatusCodes` para incluir lógica de tipos relacionados.

* Reorganização e Refatoração de Código
  - Reorganizados `using` em `HttpResultExtensions.cs` e adicionados novos métodos.
  - Refatorados `FindResult<TEntity>` e `FindResult<TEntity, TId>` para consistência de nomes.

* Atualizações de Arquivos e Funcionalidade de Rota
  - Atualizado `icon2.png` e referência em `libs.targets`.
  - Introduzida classe `RouteExtensions` para metadados automáticos em rotas.

Author: eglauko

src/Directory.Build.props

@@ -10,7 +10,7 @@
 	</PropertyGroup>
 	<PropertyGroup>
 		<SPVer>1.0.0</SPVer>
-		<SPPreview>-preview-4.7</SPPreview>
+		<SPPreview>-preview-4.8</SPPreview>
 	</PropertyGroup>
 	<PropertyGroup>
 		<FluentValidationVer>12.0.0</FluentValidationVer>

src/RoyalCode.SmartProblems.ApiResults/Metadata/ResponseTypeMetadata.cs

@@ -3,20 +3,69 @@
 
 namespace RoyalCode.SmartProblems.Metadata;
 
-internal sealed class ResponseTypeMetadata : IProducesResponseTypeMetadata
+/// <summary>
+/// Provides response metadata for an endpoint, including the CLR response <see cref="Type"/>, 
+/// HTTP <see cref="StatusCode"/>, and the allowed <see cref="ContentTypes"/>.
+/// </summary>
+/// <remarks>
+/// This type is intended to be added to endpoint metadata (e.g. via <c>WithMetadata</c>) so that
+/// tools (OpenAPI/Swagger, clients, analyzers) can infer the produced response shapes.
+/// When no content types are specified, <c>application/json</c> is assumed by default.
+/// </remarks>
+/// <example>
+/// Adding explicit metadata to an endpoint:
+/// <code>
+/// app.MapGet("/items/{id:int}", (int id) => Results.Ok(new ItemDto(id)))
+///    .WithMetadata(new ResponseTypeMetadata(typeof(ItemDto), 200));
+///
+/// app.MapPost("/items", (CreateItemDto dto) => Results.Created($"/items/1", null))
+///    .WithMetadata(new ResponseTypeMetadata(201));
+/// </code>
+/// </example>
+public sealed class ResponseTypeMetadata : IProducesResponseTypeMetadata
 {
+    /// <summary>
+    /// Initializes a new instance specifying the response <paramref name="type"/>, 
+    /// HTTP <paramref name="statusCode"/>, and optional <paramref name="contentTypes"/>.
+    /// </summary>
+    /// <param name="type">The CLR type returned in the response body (nullable for empty responses).</param>
+    /// <param name="statusCode">The HTTP status code produced by the endpoint.</param>
+    /// <param name="contentTypes">
+    /// The content types the endpoint can produce. Defaults to <c>application/json</c> when omitted.
+    /// </param>
     public ResponseTypeMetadata(Type? type, int statusCode, params string[]? contentTypes)
     {
         Type = type;
         StatusCode = statusCode;
         ContentTypes = contentTypes ?? [MediaTypeNames.Application.Json];
     }
+
+    /// <summary>
+    /// Initializes a new instance specifying only the HTTP <paramref name="statusCode"/> and optional
+    /// <paramref name="contentTypes"/> for responses where the body type is not declared or is empty.
+    /// </summary>
+    /// <param name="statusCode">The HTTP status code produced by the endpoint.</param>
+    /// <param name="contentTypes">
+    /// The content types the endpoint can produce. Defaults to <c>application/json</c> when omitted.
+    /// </param>
     public ResponseTypeMetadata(int statusCode, params string[]? contentTypes)
     {
         StatusCode = statusCode;
         ContentTypes = contentTypes ?? [MediaTypeNames.Application.Json];
     }
+
+    /// <summary>
+    /// Gets the CLR type returned in the response body (if any).
+    /// </summary>
     public Type? Type { get; }
+
+    /// <summary>
+    /// Gets the HTTP status code produced by the endpoint.
+    /// </summary>
     public int StatusCode { get; }
+
+    /// <summary>
+    /// Gets the sequence of content types the endpoint can produce.
+    /// </summary>
     public IEnumerable<string> ContentTypes { get; }
 }

src/RoyalCode.SmartProblems.ApiResults/Metadata/RouteExtensions.cs

@@ -0,0 +1,59 @@
+using Microsoft.AspNetCore.Mvc;
+using RoyalCode.SmartProblems;
+using RoyalCode.SmartProblems.Metadata;
+using System.Reflection;
+
+namespace Microsoft.AspNetCore.Builder;
+
+/// <summary>
+/// Provides extension methods for <see cref="RouteHandlerBuilder"/> to populate endpoint metadata
+/// based on custom attributes, such as <see cref="ProduceProblemsAttribute"/>.
+/// </summary>
+public static class RouteExtensions
+{
+    /// <summary>
+    /// <para>
+    ///     Populates the endpoint metadata for the specified <see cref="RouteHandlerBuilder"/> using the metadata
+    ///     defined on the type parameter <typeparamref name="T"/>.
+    /// </para>
+    /// <para>
+    ///     This is typically used to add response metadata for problem details based 
+    ///     on the <see cref="ProduceProblemsAttribute"/> applied to <typeparamref name="T"/>.
+    /// </para>
+    /// </summary>
+    /// <typeparam name="T">The type to inspect for metadata attributes.</typeparam>
+    /// <param name="builder">The route handler builder to populate metadata for.</param>
+    /// <returns>The same <see cref="RouteHandlerBuilder"/> instance for chaining.</returns>
+    public static RouteHandlerBuilder PopulateMetadata<T>(this RouteHandlerBuilder builder)
+        => PopulateMetadata(builder, typeof(T));
+
+    /// <summary>
+    /// <para>
+    ///     Populates the endpoint metadata for the specified <see cref="RouteHandlerBuilder"/> using the metadata
+    ///     defined on the provided <paramref name="type"/>. 
+    /// </para>
+    /// <para>
+    ///     If the type is decorated with <see cref="ProduceProblemsAttribute"/>,
+    ///     it will add <see cref="ResponseTypeMetadata"/> for each status code specified in the attribute.
+    /// </para>
+    /// </summary>
+    /// <param name="builder">The route handler builder to populate metadata for.</param>
+    /// <param name="type">The type to inspect for metadata attributes.</param>
+    /// <returns>The same <see cref="RouteHandlerBuilder"/> instance for chaining.</returns>
+    public static RouteHandlerBuilder PopulateMetadata(this RouteHandlerBuilder builder, Type type)
+    {
+        var attr = type.GetCustomAttribute<ProduceProblemsAttribute>();
+        if (attr is not null)
+        {
+            Type responseType = typeof(ProblemDetails);
+            string[] content = ["application/problem+json"];
+
+            foreach (var statusCode in attr.GetStatusCodes())
+            {
+                builder.WithMetadata(new ResponseTypeMetadata(responseType, statusCode, content));
+            }
+        }
+        return builder;
+    }
+}
+

src/RoyalCode.SmartProblems.ApiResults/ProduceProblemsAttribute.cs

@@ -1,4 +1,6 @@
 
+using System.Reflection;
+
 namespace RoyalCode.SmartProblems;
 
 /// <summary>
@@ -17,6 +19,11 @@ public sealed class ProduceProblemsAttribute : Attribute
     /// </summary>
     public ProblemCategory[]? Categories { get; set; }
 
+    /// <summary>
+    /// A related type that can be used to provide additional context for the problems produced by the method.
+    /// </summary>
+    public Type? RelatedType { get; set; }
+
     /// <summary>
     /// Define the categories of problems that the method produces for problems results.
     /// </summary>
@@ -35,6 +42,15 @@ public ProduceProblemsAttribute(params int[] statusCodes)
         StatusCodes = statusCodes;
     }
 
+    /// <summary>
+    /// Define the related type that can be used to provide additional context for the problems produced by the method.
+    /// </summary>
+    /// <param name="relatedType">The related type that can be used to provide additional context for the problems produced by the method.</param>
+    public ProduceProblemsAttribute(Type relatedType)
+    {
+        RelatedType = relatedType;
+    }
+
     /// <summary>
     /// Define the status codes and categories of problems that the method produces for problems results.
     /// </summary>
@@ -46,30 +62,63 @@ public ProduceProblemsAttribute(int[] statusCodes, ProblemCategory[] categories)
         Categories = categories;
     }
 
+    /// <summary>
+    /// Define the status codes and categories of problems that the method produces for problems results.
+    /// </summary>
+    /// <param name="relatedType">The related type that can be used to provide additional context for the problems produced by the method.</param>
+    /// <param name="categories">The problem categories that the method produces for problems results.</param>
+    public ProduceProblemsAttribute(Type relatedType, ProblemCategory[] categories)
+    {
+        RelatedType = relatedType;
+        Categories = categories;
+    }
+
+    /// <summary>
+    /// Define the status codes and categories of problems that the method produces for problems results.
+    /// </summary>
+    /// <param name="relatedType">The related type that can be used to provide additional context for the problems produced by the method.</param>
+    /// <param name="statusCodes">The status codes that the method produces for problems results.</param>
+    /// <param name="categories">The problem categories that the method produces for problems results.</param>
+    public ProduceProblemsAttribute(Type relatedType, int[] statusCodes, ProblemCategory[] categories)
+    {
+        RelatedType = relatedType;
+        StatusCodes = statusCodes;
+        Categories = categories;
+    }
+
     /// <summary>
     /// Creates a new instance of <see cref="ProduceProblemsAttribute"/>.
     /// </summary>
     public ProduceProblemsAttribute() { }
 
-    internal IEnumerable<int> GetStatusCodes()
+    /// <summary>
+    /// Obtains the status codes that this attribute produces for problems results.
+    /// </summary>
+    /// <returns>
+    /// An <see cref="IEnumerable{Int32}"/> containing the status codes that this attribute produces for problems results.
+    /// </returns>
+    public IEnumerable<int> GetStatusCodes()
     {
         if (StatusCodes is not null)
-            foreach (var statusCode in StatusCodes)
-                yield return statusCode;
+            for (var i = 0; i < StatusCodes.Length; i++)
+                yield return StatusCodes[i];
+
+        if (Categories is not null)
+            for (var i = 0; i < Categories.Length; i++)
+                yield return Categories[i] switch
+                {
+                    ProblemCategory.NotFound => 404,
+                    ProblemCategory.InvalidParameter => 400,
+                    ProblemCategory.ValidationFailed => 422,
+                    ProblemCategory.CustomProblem => 422,
+                    ProblemCategory.InvalidState => 409,
+                    ProblemCategory.InternalServerError => 500,
+                    _ => 400
+                };
 
-        if (Categories is null) 
-            yield break;
-        
-        foreach (var category in Categories)
-            yield return category switch
-            {
-                ProblemCategory.NotFound => 404,
-                ProblemCategory.InvalidParameter => 400,
-                ProblemCategory.ValidationFailed => 422,
-                ProblemCategory.InvalidState => 409,
-                ProblemCategory.NotAllowed => 403,
-                ProblemCategory.InternalServerError => 500,
-                _ => 400
-            };
+        var attr = RelatedType?.GetCustomAttribute<ProduceProblemsAttribute>();
+        if (attr != null)
+            foreach (var code in attr.GetStatusCodes())
+                yield return code;
     }
 }

src/RoyalCode.SmartProblems.Http/HttpResultExtensions.cs

@@ -1,9 +1,10 @@
 using RoyalCode.SmartProblems;
 using RoyalCode.SmartProblems.Conversions;
+using RoyalCode.SmartProblems.Http;
 using System.Net.Http.Json;
 using System.Runtime.CompilerServices;
 using System.Text.Json;
-using RoyalCode.SmartProblems.Http;
+using System.Text.Json.Serialization.Metadata;
 
 // ReSharper disable CheckNamespace
 
@@ -73,6 +74,26 @@ public static Task<Result<TValue>> ToResultAsync<TValue>(
         return ToResultAsync<TValue>(response, null, options, token);
     }
 
+    /// <summary>
+    /// <para>
+    ///     Get <see cref="Result{TValue}" /> from <see cref="HttpResponseMessage"/>.
+    /// </para>
+    /// </summary>
+    /// <typeparam name="TValue">The type of the value.</typeparam>
+    /// <param name="response">The <see cref="HttpResponseMessage"/>.</param>
+    /// <param name="jsonTypeInfo">
+    ///     The <see cref="JsonTypeInfo{T}"/> for the <typeparamref name="TValue"/>, 
+    ///     used when status code is success.
+    /// </param>
+    /// <param name="ct">The <see cref="CancellationToken"/>.</param>
+    /// <returns>The <see cref="Result{TValue}"/>.</returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static Task<Result<TValue>> ToResultAsync<TValue>(
+        this HttpResponseMessage response, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken ct = default)
+    {
+        return ToResultAsync(response, null, jsonTypeInfo, ct);
+    }
+
     /// <summary>
     /// <para>
     ///     Get <see cref="Result{TValue}" /> from <see cref="HttpResponseMessage"/>.
@@ -106,6 +127,39 @@ public static async Task<Result<TValue>> ToResultAsync<TValue>(
         return value!;
     }
 
+    /// <summary>
+    /// <para>
+    ///     Get <see cref="Result{TValue}" /> from <see cref="HttpResponseMessage"/>.
+    /// </para>
+    /// </summary>
+    /// <typeparam name="TValue">The type of the value.</typeparam>
+    /// <param name="response">The <see cref="HttpResponseMessage"/>.</param>
+    /// <param name="failureTypeReader">
+    ///     A <see cref="FailureTypeReader"/> to read the error content when the status code is not success 
+    ///     and the content is not a problem details.
+    /// </param>
+    /// <param name="jsonTypeInfo">
+    ///     The <see cref="JsonTypeInfo{T}"/> for the <typeparamref name="TValue"/>, 
+    ///     used when status code is success.
+    /// </param>
+    /// <param name="ct">The <see cref="CancellationToken"/>.</param>
+    /// <returns>The <see cref="Result{TValue}"/>.</returns>
+    public static async Task<Result<TValue>> ToResultAsync<TValue>(
+        this HttpResponseMessage response,
+        FailureTypeReader? failureTypeReader,
+        JsonTypeInfo<TValue> jsonTypeInfo,
+        CancellationToken ct = default)
+    {
+        // on error, read the content as a problem details or text.
+        if (!response.IsSuccessStatusCode)
+            return await response.ReadErrorStatus(failureTypeReader, ct);
+
+        // on success, with value, the value must be deserialized
+        var value = await response.Content.ReadFromJsonAsync(jsonTypeInfo, ct);
+
+        return value!;
+    }
+
     private static Task<Problems> ReadErrorStatus(
         this HttpResponseMessage response, FailureTypeReader? failureTypeReader, CancellationToken token)
     {