.NET9: Microsoft.AspNetCore.OpenApi.OpenApiSchemaService should not be internal

[jornhd]

Background and Motivation

As Swashbuckle is no longer supported in .NET 9, we've started migrating our operation filters to operation transformers to prepare for the .NET 9 release.

In some of our current Swashbuckle filters, we need to add types to the schema that isn't described in the ApiDescription, in order to reference these types in eg. operation.Responses.

We do this today with the following line:
var schema = context.SchemaGenerator.GenerateSchema(myType, context.SchemaRepository);

We tried to do the same in our IOpenApiOperationTransformer implementation:

var componentService = context.ApplicationServices.GetRequiredKeyedService<OpenApiSchemaService>(context.DocumentName);
var schema = await componentService.GetOrCreateSchemaAsync(myType, null, true, cancellationToken);

The problem is that OpenApiSchemaService is internal, not public, so it's impossible to add schema for additional types.

Proposed API

Make OpenApiSchemaService public, or provide GetOrCreateSchemaAsync in a public api, preferable the OpenApiOperationTransformerContext.

[martincostello]

As Swashbuckle is no longer supported in .NET 9

I assume you mean "not included in the ASP.NET Core 9 templates"? Swashbuckle.AspNetCore itself is still supported by its maintainers (of which I'm one), and there's support for .NET 9 in progress: domaindrivendev/Swashbuckle.AspNetCore#3007

it's impossible to add schema for additional types

You should be able to add additional schema components using IOpenApiOperationTransformer (via adding additional requests/responses) or via IOpenApiDocumentTransformer by adding components to the OpenApiDocument. You shouldn't need to have access to the internal implementation details to change the OpenAPI document like that.

[jornhd]

You should be able to add additional schema components using IOpenApiOperationTransformer (via adding additional requests/responses)

That's exactly what I'm trying to do! The problem is how do we create the schema for a type?

One example: The API is set up to handle and return exceptions as a custom type ErrorResponse.
Instead of setting this response type with attribute on every single method, we do this today in an OperationFilter.

Migrating this filter to an IOpenApiOperationTransformer implementation, we have this code:

public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
{
    if (operation.Responses.ContainsKey("500"))
    {
        return Task.CompletedTask;
    }
    
    // Next line is old Swashbuckle code - How can we do convert the type ErrorResponse to OpenApiSchema using IOpenApiOperationTransformer?
    // var schema = context.SchemaGenerator.GenerateSchema(typeof(ErrorResponse), context.SchemaRepository);

    var serverError = new OpenApiResponse
    {
        Description = "Server Error",
        Content =
        {
            { "application/json", new OpenApiMediaType { Schema = schema } }
        }
    };
    operation.Responses.Add("500", serverError);

    return Task.CompletedTask;
}

So the problem is, when we can't access the OpenApiSchemaService.GetOrCreateSchemaAsync, how are we supposed to get the schema for the custom type ErrorRespose?

[martincostello]

My understanding is that, given a type, you can use the new JsonSchemaExporter.GetJsonSchemaAsNode() method, like the service does here to create a schema.

var schemaObject = JsonSchemaExporter.GetJsonSchemaAsNode(jsonSerializerOptions, typeof(ErrorResponse), jsonSchemaExporterOptions);
// Create an OpenApiSchema from the JsonNode returned above

That's not something I've done myself though. Rather than get into adding a schema directly, I've instead added metadata to the API endpoints to add additional produces metadata (e.g. ProducesProblem()), and then the internals add it to the schema automatically.

[jornhd]

Ok, so we basically need to copy most of the service (the jsonSchemaExporterOptions is huge, and we still need to deserialize JsonNode). It would have been nice to have this in a public method like Swashbuckle has.

[captainsafia]

@jornhd Thanks for filing this issue and trying out the new APIs.

The choice to make the OpenApiSchemaService internal as part of this release was intentional. As mentioned in this thread, the current OpenApiSchemaService implementation depends on the new JsonSchemaExporter APIs in STJ for generating schemas. There are some OpenAPI-specific mappings in our options object that are required when targeting Open API v3.0. We're hoping to add support for OpenAPI v3.1 in the future, which will change the shape and requirements of the schema service. So the choice to not make the APIs public at the moment is to give us the flexibility to design the right API in the future.

I do have one curious question about your scenario though. Where is the ErrorResponse type that you're returning manifesting in your API? Are you using middleware or filters to generate the response type?

I'd +1 @martincostello's recommendation above: if you can you should use ProducesProblem (there are ways to only call it once) to convey to the application that it returns that type. That way, that behavior is codified in the metadata of the APIs and isn't just superficially in the OpenAPI document. It also means you don't have to author transformers/filters for each OpenAPI package to configure this behavior.

[jornhd]

I do have one curious question about your scenario though. Where is the ErrorResponse type that you're returning manifesting in your API? Are you using middleware or filters to generate the response type?

We do this using middleware.

I've learned now that we can add the response type to all methods by adding a custom convention with AddControllers option action. I guess we can do something similar in MinimalApi.

@martincostello @captainsafia Thanks for your inputs. You can close this issue.

[dotnet-policy-service]

This issue has been resolved and has not had any activity for 1 day. It will be closed for housekeeping purposes.

See our Issue Management Policies for more information.