OpenApi: Add a way to add schema's based on Type instead of custom mapping

[desjoerd]

In Microsoft.AspNetCore.OpenApi there is currently no way to reuse all built logic around schema transformers, updating/patching the schema based on System.Text.Json.Schemas because everything is internal. I understand why it's all hidden because that would increase the Api surface, but it makes it really hard to push your own schemas based on Type as you need to "copy" or "build" all that logic around mapping the JsonNode schema to the Microsoft.OpenApi JsonSchema yourself and cannot hook into already registered schema transformers. It would be awesome if we can add Json Schemas based on Type which would (re-)use the current logic provided in Microsoft.AspNetCore.OpenApi and for those schemas it would also apply all schema transformers.

This would greatly enhance Microsoft.AspNetCore.OpenApi for the following scenario's:

• Pushing default responses (which aren't part of the metadata). For example with ProblemDetails or your own model. Currently you need to create a schema manually and push it in the document.
• Wrapper types, for example my OptionalValues package. I now need to copy all logic of Microsoft.AspNetCore.OpenApi to be able to handle wrapped complex types.
• Handling complex types which have a custom json converter with references to other complex types. The moment you have a custom json converter you hit a big wall and you are on your own for all nested properties.

It would be great if the OpenApiOptions or the OpenApiSchemaService exposed a GetOrCreateSchema(Type) method.

[martincostello]

I forget exactly where in the stream, but there's a discussion about how this sort of thing will be enabled as part of the .NET 10 release: 📺 ASP.NET Community Standup - Exciting (and breaking) changes for OpenAPI in .NET 10

[desjoerd]

Awesome, will watch that. I was already hacking a weird work around with generating fake Mvc Api Descriptions with the models I need to then remove those fake endpoints in a document transformer.

[desjoerd]

This is really dirty, but it works 😶‍🌫️

builder.Services.AddOpenApi(x =>
{
    x.AddDocumentTransformer(new RemoveAddSchemaEndpointsOpenApiDocumentTrasformer());
});
builder.Services.AddTransient<IApiDescriptionProvider>(_ => new AddSchemaApiDescriptionProvider(typeof(Address)));
builder.Services.AddTransient<IApiDescriptionProvider>(_ => new AddSchemaApiDescriptionProvider(typeof(Person)));

public class AddSchemaApiDescriptionProvider : IApiDescriptionProvider
{
    private readonly Type _type;

    public AddSchemaApiDescriptionProvider(Type type)
    {
        _type = type;
    }

    public void OnProvidersExecuting(ApiDescriptionProviderContext context)
    {
        context.Results.Add(new ApiDescription
        {
            HttpMethod = "GET",
            RelativePath = "/add-schema/" + _type.FullName,
            Properties = { {"type", _type } },
            ActionDescriptor = new ActionDescriptor
            {
                DisplayName = "Add Schema " + _type.FullName,
                EndpointMetadata = new List<object>
                {
                    new TagsAttribute("SCHEMA_FAKE_ENDPOINT")
                }
            },
            SupportedResponseTypes =
            {
                new ApiResponseType()
                {
                    StatusCode = 200,
                    Type = _type,
                    ApiResponseFormats =
                    {
                        new ApiResponseFormat
                        {
                            MediaType = "application/json"
                        }
                    }
                }
            }
        });
    }

    public void OnProvidersExecuted(ApiDescriptionProviderContext context) { }

    public int Order { get; }
}

public class RemoveAddSchemaEndpointsOpenApiDocumentTrasformer : IOpenApiDocumentTransformer
{
    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        foreach(var pathToRemove in document.Paths.Keys.Where(k => k.StartsWith("/add-schema/")).ToList())
        {
            document.Paths.Remove(pathToRemove);
        }

        return Task.CompletedTask;
    }
}

[desjoerd]

@martincostello it's at the end of the stream, very helpfull :).

From what I understand is that the new models of the v2 OpenApi.NET package make it a lot more accessible to add new schemas or references to schemas. (so no more x-schema-id reference).

I had a few things which are still unclear to me.

• Will custom schema's which we add also get a pass with all the ISchemaTransformers
• I can't find a way (or issue) for adding schema's based on the JsonNode from the STJ JsonSchemaExporter.

There is quite some (internal) logic mapping the Schema in the form of a JsonNode from STJ to an OpenApi.NET JsonSchema object (including applying DataAnnotations). It would be awesome if we can "easily" re-use that :).