Expose additional info about properties and JSON types in OpenApiSchemaTransformerContext

[captainsafia]

Background and Motivation

OpenAPI schema transformers currently only run on schemas that are generated at the top-level for parameters and responses. For example, in the following case:

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options => 
{
    options.UseSchemaTransformer((schema, context, ct) =>
    {
        if (context.Type == typeof(int))
        {
            schema.Format = "some-custom-format";
        }
    }
});

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos/{id}", (int id) => Results.Ok<Todo>(new Todo()));

public record Todo(int Id, string Name, bool IsCompleted);

The transformer will only apply the modification on the schema generated for the id route parameter and not the id property within Todo. To resolve this issue, schemas need to be applied recursively into properties and child schemas (like those in anyOf and allOf). To support this, the implementation will apply transformers on child schemas. As part of this work, we need to expose additional APIs on OpenApiSchemaTransformerContext in order to be able to analyze

Proposed API

// Assembly: Microsoft.AspNetCore.OpenApi;

namespace Microsoft.AspNetCore.OpenApi;

public sealed class OpenApiSchemaTransformerContext
{
+   public JsonTypeInfo TypeInfo { get; init; }
+   public JsonPropertyInfo? PropertyInfo { get; init; }
}

Usage Examples

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options => 
{
    options.UseSchemaTransformer((schema, context, ct) =>
    {
        if (context.Type == typeof(int))
        {
            if (context.PropertyInfo is { AttributeProvider: { } attributeProvider } jsonPropertyInfo)
            {
                if (attributeProvider.GetCustomAttributes(inherit: false).OfType<MyCustomAttribute>().LastOrDefault() is {} attr)
                {
                    schema.Description = attr.Value;
                }
            }
            schema.Format = "some-custom-format";
        }
    }
});

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos/{id}", (int id) => Results.Ok<Todo>(new Todo()));

public record Todo(int Id, string Name, bool IsCompleted);

Alternative Designs

• Provide TypeInfo and PropertyInfo instead of JsonTypeInfo and JsonPropertyInfo?
• Should properties only expose public accessors instead of initializers as well?

Risks

• This API shape requires that users apply a null-check to disambiguate if they are in the schema for a property or not.
• This API shape does not provide a consistent way to determine if a sub-schema that is being generated is in the anyOf of a parent type.

[dotnet-policy-service[bot]]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[mikekistler]

Are you expecting users to code the recursion into subschemas themselves or will that be done by the framework? I'm hoping it is the latter, and that the new context fields are needed to implement that.

[captainsafia]

It's the later. The implementation referenced in the proposal is referring to the framework.

To support this, the implementation will apply transformers on child schemas. As part of this work, we need to expose additional APIs on OpenApiSchemaTransformerContext in order to be able to analyze

[halter73]

API Review Notes:

• Can the UseSchemaTransformer callback be called multiple times for the same type?
  • Yes. It was per-type and will be per property.
• Do we want to use TypeInfo and PropertyInfo instead of JsonTypeInfo and JsonPropertyInfo?
  • No. We can get can get TypeInfo from JsonTypeInfo but not vice-versa. We might as well provide as much info as possible for things like JSON capitalization.
  • JsonTypeInfo might be mutable, but that's okay.
• Can JsonTypeInfo be null in valid scenarios?
  • We don't think so. Even for reflection only scenarios, there should be an instance.
• Should we rename TypeInfo to JsonTypeInfo and PropertyInfo to JsonPropertyInfo?
  • Yes. Otherwise, it looks like it's the reflection types and not the S.T.J ones even though an IDE would clarify this.
• Should we get rid of the Type property now that it's redundant?
  • Yes
• Should JsonTypeInfo be required?
  • Yes
• Should we make the OpenApiSchemaTransformerContext (and other contexts) so it can only be constructed internally?
  • Let's let people construct them for testing

API Approved!

// Assembly: Microsoft.AspNetCore.OpenApi;

namespace Microsoft.AspNetCore.OpenApi;

public sealed class OpenApiSchemaTransformerContext
{
-   public required Type Type { get; init; }
+   public required JsonTypeInfo JsonTypeInfo { get; init; }
+   public JsonPropertyInfo? JsonPropertyInfo { get; init; }
}