Add support for OpenAPI schema transformers

[captainsafia]

This PR adds support for the OpenAPI schema transformers API to the built-in generator.

Schema Transformer:

• src/OpenApi/src/Services/OpenApiOptions.cs: Added a new UseSchemaTransformer method that allows users to register a delegate as a schema transformer. This method adds the provided transformer delegate to the SchemaTransformers list. [1] [2]
• src/OpenApi/perf/Microbenchmarks/TransformersBenchmark.cs: A new SchemaTransformer_Setup method has been added. This method sets up a new schema transformer that adds an extension to the schema based on the context. A new benchmark method, SchemaTransformer, has also been added. [1] [2]

Method	TransformerCount	Mean	Error	StdDev	Op/s	Gen 0	Gen 1	Gen 2	Allocated
SchemaTransformer	10	10.01 us	0.096 us	0.085 us	99,938.4	0.1221	-	-	20 KB
SchemaTransformer	100	13.01 us	0.141 us	0.110 us	76,890.6	0.1831	-	-	25 KB
SchemaTransformer	1000	40.00 us	0.289 us	0.242 us	25,002.0	0.4883	-	-	82 KB

Additional Changes:

• src/OpenApi/src/PublicAPI.Unshipped.txt: Added new entries related to the OpenApiSchemaTransformerContext class and the UseSchemaTransformer method in the OpenApiOptions class.
• src/OpenApi/perf/Microbenchmarks/TransformersBenchmark.cs: Imported the Microsoft.OpenApi.Any namespace.

[davidfowl]

Can these transformers access the IServiceProvider?

[JamesNK]

What are scenarios where someone could have an async schema transformer?

[JamesNK]

Is async reading an XML comments file from disk and then applying changes to the schema an example?

[captainsafia]

XML comments support will be handled separately in this implementation, although theoretically there's nothing stopping someone from rolling out an implementation on their own or reading additional metadata from some non-XML file.

[JamesNK]

Can these transformers access the IServiceProvider?

There is OpenApiSchemaTransformerContext.ApplicationServices.

[captainsafia]

Can these transformers access the IServiceProvider?

In addition to the property on the context object @JamesNK mentioned above, we also have a generic API for supporting resolving activated instances of a transformer OpenApiOptions.UseTransformer<T>. To keep the API small, we've only exposed it for document transformers at the moment but it's a pattern we can expand to other transformers as the need arises (e.g. there's an API proposal to add it. for operation transformers).

[BrennanConroy]

Nit: Should add a test for checking DocumentName and ApplicationServices.

[halter73]

Did we discuss Use...Transformer vs Add...Transformer in API review? I only ask because we went with AddEndpointFilter over UseEndpointFilter in .NET 7, and this feels even more addy so-to-speak since there can be multiples of each type of transformer and there's no next callback unlike filters and middleware.

[captainsafia]

Did we discuss Use...Transformer vs Add...Transformer in API review? I only ask because we went with AddEndpointFilter over UseEndpointFilter in .NET 7, and this feels even more addy so-to-speak since there can be multiples of each type of transformer and there's no next callback unlike filters and middleware.

We discussed the similarities/differences between transformers and middleware/filters. Looking back at the notes, it doesn't look like we discussed Use vs Add specifically.

I have a slight preference towards Add myself. We can discuss this rename at the upcoming review around adding an interface type for operation transformers.