Add support for generating JSON schemas in OpenAPI doc (#55208)

Author: captainsafia

eng/Dependencies.props

@@ -228,6 +228,7 @@ and are generated based on the last package release.
     <LatestPackageReference Include="StackExchange.Redis" />
     <LatestPackageReference Include="Swashbuckle.AspNetCore" />
     <LatestPackageReference Include="System.Reactive.Linq" />
+    <LatestPackageReference Include="Verify.Xunit" />
     <LatestPackageReference Include="xunit.abstractions" />
     <LatestPackageReference Include="xunit.analyzers" />
     <LatestPackageReference Include="xunit.assert" />

eng/Versions.props

@@ -326,6 +326,7 @@
     <StackExchangeRedisVersion>2.7.27</StackExchangeRedisVersion>
     <SystemReactiveLinqVersion>5.0.0</SystemReactiveLinqVersion>
     <SwashbuckleAspNetCoreVersion>6.4.0</SwashbuckleAspNetCoreVersion>
+    <VerifyXunitVersion>19.14.0</VerifyXunitVersion>
     <XunitAbstractionsVersion>2.0.3</XunitAbstractionsVersion>
     <XunitAnalyzersVersion>1.0.0</XunitAnalyzersVersion>
     <XunitVersion>2.4.2</XunitVersion>

src/Mvc/Mvc.Core/src/Microsoft.AspNetCore.Mvc.Core.csproj

@@ -90,6 +90,7 @@ Microsoft.AspNetCore.Mvc.RouteAttribute</Description>
     <InternalsVisibleTo Include="Microsoft.AspNetCore.Mvc.ViewFeatures.Test" />
     <InternalsVisibleTo Include="Microsoft.AspNetCore.Mvc.Views.TestCommon" />
     <InternalsVisibleTo Include="Microsoft.AspNetCore.Mvc.Microbenchmarks" />
+    <InternalsVisibleTo Include="Microsoft.AspNetCore.OpenApi.Tests" />
     <InternalsVisibleTo Include="DynamicProxyGenAssembly2" Key="$(MoqPublicKey)" />
   </ItemGroup>
 </Project>

src/OpenApi/sample/Controllers/TestController.cs

@@ -0,0 +1,24 @@
+using System.ComponentModel.DataAnnotations;
+using Microsoft.AspNetCore.Mvc;
+
+[ApiController]
+[Route("[controller]")]
+public class TestController : ControllerBase
+{
+    [HttpGet]
+    [Route("/getbyidandname/{id}/{name}")]
+    public string GetByIdAndName(RouteParamsContainer paramsContainer)
+    {
+        return paramsContainer.Id + "_" + paramsContainer.Name;
+    }
+
+    public class RouteParamsContainer
+    {
+        [FromRoute]
+        public int Id { get; set; }
+
+        [FromRoute]
+        [MinLength(5)]
+        public string? Name { get; set; }
+    }
+}

src/OpenApi/sample/Program.cs

@@ -7,6 +7,7 @@
 
 var builder = WebApplication.CreateBuilder(args);
 
+builder.Services.AddControllers();
 builder.Services.AddAuthentication().AddJwtBearer();
 
 builder.Services.AddOpenApi("v1", options =>
@@ -51,6 +52,8 @@
 var responses = app.MapGroup("responses")
     .WithGroupName("responses");
 
+v1.MapGet("/array-of-guids", (Guid[] guids) => guids);
+
 v1.MapPost("/todos", (Todo todo) => Results.Created($"/todos/{todo.Id}", todo))
     .WithSummary("Creates a new todo item.");
 v1.MapGet("/todos/{id}", (int id) => new TodoWithDueDate(1, "Test todo", false, DateTime.Now.AddDays(1), DateTime.Now))
@@ -67,4 +70,13 @@
 responses.MapGet("/200-only-xml", () => new TodoWithDueDate(1, "Test todo", false, DateTime.Now.AddDays(1), DateTime.Now))
     .Produces<Todo>(contentType: "text/xml");
 
+responses.MapGet("/triangle", () => new Triangle { Color = "red", Sides = 3, Hypotenuse = 5.0 });
+responses.MapGet("/shape", () => new Shape { Color = "blue", Sides = 4 });
+
+app.MapControllers();
+
 app.Run();
+
+// Make Program class public to support snapshot testing
+// against sample app using WebApplicationFactory.
+public partial class Program { }

src/OpenApi/sample/Transformers/OperationTransformers.cs

@@ -16,6 +16,7 @@ public static OpenApiOptions AddHeader(this OpenApiOptions options, string heade
         {
             var schema = OpenApiTypeMapper.MapTypeToOpenApiPrimitiveType(typeof(string));
             schema.Default = new OpenApiString(defaultValue);
+            operation.Parameters ??= [];
             operation.Parameters.Add(new OpenApiParameter
             {
                 Name = headerName,

src/OpenApi/src/Extensions/JsonObjectSchemaExtensions.cs

@@ -0,0 +1,86 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Linq;
+using System.Reflection;
+using System.Text.Json.Serialization.Metadata;
+
+namespace JsonSchemaMapper;
+
+/// <summary>
+/// Defines the context in which a JSON schema within a type graph is being generated.
+/// </summary>
+#if EXPOSE_JSON_SCHEMA_MAPPER
+public
+#else
+internal
+#endif
+    readonly struct JsonSchemaGenerationContext
+{
+    internal JsonSchemaGenerationContext(JsonTypeInfo typeInfo, Type? declaringType, JsonPropertyInfo? propertyInfo, ParameterInfo? parameterInfo)
+    {
+        TypeInfo = typeInfo;
+        DeclaringType = declaringType;
+        PropertyInfo = propertyInfo;
+        ParameterInfo = parameterInfo;
+    }
+
+    /// <summary>
+    /// The <see cref="JsonTypeInfo"/> for the type being processed.
+    /// </summary>
+    public JsonTypeInfo TypeInfo { get; }
+
+    /// <summary>
+    /// The declaring type of the property or parameter being processed.
+    /// </summary>
+    public Type? DeclaringType { get; }
+
+    /// <summary>
+    /// The <see cref="JsonPropertyInfo"/> if the schema is being generated for a property.
+    /// </summary>
+    public JsonPropertyInfo? PropertyInfo { get; }
+
+    /// <summary>
+    /// The <see cref="System.Reflection.ParameterInfo"/> if a constructor parameter
+    /// has been associated with the accompanying <see cref="PropertyInfo"/>.
+    /// </summary>
+    public ParameterInfo? ParameterInfo { get; }
+
+    /// <summary>
+    /// Checks if the type, property, or parameter has the specified attribute applied.
+    /// </summary>
+    /// <typeparam name="TAttribute">The type of the attribute to resolve.</typeparam>
+    /// <param name="inherit">Whether to look up the hierarchy chain for the inherited custom attribute.</param>
+    /// <returns>True if the attribute is defined by the current context.</returns>
+    public bool IsDefined<TAttribute>(bool inherit = false)
+        where TAttribute : Attribute =>
+        GetCustomAttributes(typeof(TAttribute), inherit).Any();
+
+    /// <summary>
+    /// Checks if the type, property, or parameter has the specified attribute applied.
+    /// </summary>
+    /// <typeparam name="TAttribute">The type of the attribute to resolve.</typeparam>
+    /// <param name="inherit">Whether to look up the hierarchy chain for the inherited custom attribute.</param>
+    /// <returns>The first attribute resolved from the current context, or null.</returns>
+    public TAttribute? GetAttribute<TAttribute>(bool inherit = false)
+        where TAttribute : Attribute =>
+        (TAttribute?)GetCustomAttributes(typeof(TAttribute), inherit).FirstOrDefault();
+
+    /// <summary>
+    /// Resolves any custom attributes that might have been applied to the type, property, or parameter.
+    /// </summary>
+    /// <param name="type">The attribute type to resolve.</param>
+    /// <param name="inherit">Whether to look up the hierarchy chain for the inherited custom attribute.</param>
+    /// <returns>An enumerable of all custom attributes defined by the context.</returns>
+    public IEnumerable<Attribute> GetCustomAttributes(Type type, bool inherit = false)
+    {
+        // Resolves attributes starting from the property, then the parameter, and finally the type itself.
+        return GetAttrs(JsonSchemaMapper.ResolveAttributeProvider(DeclaringType, PropertyInfo))
+            .Concat(GetAttrs(ParameterInfo))
+            .Concat(GetAttrs(TypeInfo.Type))
+            .Cast<Attribute>();
+
+        object[] GetAttrs(ICustomAttributeProvider? provider) =>
+            provider?.GetCustomAttributes(type, inherit) ?? Array.Empty<object>();
+    }
+}