The best way to add a body example

[crwsolutions]

Hi there, I hope someone can help me out, I just need a little confirmation:

I am working on a Minimal Api with the new OpenApi lib. I am trying to add a body example to an endpoint. After many hours (more on that later) I managed to get it working using IOpenApiOperationTransformer (within the TransformAsync() the OperationId is checked, to put the body-example in the right place).

The documentation. states:

Use a document transformer or an operation transformer to set the example, examples, or encoding fields, or to add specification extensions for the request body in the generated OpenAPI document.

My code:

public class ExampleOperationFilter : IOpenApiOperationTransformer
{
    public Task TransformAsync(
        OpenApiOperation operation,
        OpenApiOperationTransformerContext context,
        CancellationToken cancellationToken
    )
    {
        if (operation.OperationId == "GenerateDetailedFinancialReport")
        {
            operation
                .RequestBody.Content["application/json"]
                .Examples.Add(
                    "FinancialReportExample",
                    FinancialCalculationRequestExample.GetExample()
                );
        }

        return Task.CompletedTask;
    }
}

And register that with:

.AddOpenApi(options =>
{
    options.AddOperationTransformer<ExampleOperationFilter>();
}

My hours have been spent on AI and me offcourse not reading documentation, because that keeps pointing me to use WithOpenApi() on the endpoint, but this does nothing (as documented I guess it states:

This method does not integrate with built-in OpenAPI document generation support in ASP.NET Core and is primarily intended for consumption along-side Swashbuckle.AspNetCore.

somewhere). So is this currently the only way? It feels logical that I can add something to the MapPost() To get it working. 'Example' is also such a hard google term, so thats why I added this issue.

@mikekistler informed me that:

In .NET 9 (currently) the only way to add an example is with a transformer. There is already support for xmldoc comments added in the .NET 10 development stream and this includes support for the tag, which will allow examples to be added in many cases without a transformer.

[captainsafia]

@crwsolutions Yes, at the moment. The IOpenApiOperationTransformer is the only way to add examples to the request body.

The WithOpenApi extension method predates the built-in OpenAPI support. In .NET 9, we decided to leave that API as-is with support only in Swashbuckle.AspNetCore. You can read more about this in this issue.

With that being said, I've opened #59180 with a proposal on bringing a WithOpenApi-like API to the built-in support. Feel free to chime in with your thoughts on that issue.

[crwsolutions]

Hi @captainsafia,

With that being said, I've opened #59180 with a proposal on bringing a WithOpenApi-like API to the built-in support. Feel free to chime in with your thoughts on that issue.

Yes that is exactly what we need. I hope you guys get that realeased soon. Did you also thought of an implementation? Is that something I can add for the time being?

I have also created an feature request to highlight the remarks on the visual studio side, please upvote :):
https://developercommunity.visualstudio.com/t/Highlight-xml-doc/10827622?port=1026&fsid=1f3b8f31-6daa-436e-bf4b-22a37bd8f697

[captainsafia]

@crwsolutions I do have my mockup implementation for this that you can look at over at f200ce5.

You'll need to implement the logic in the OpenApiDocumentService in your own document transformer that looks through the api descriptions and pulls the transformer definition from metadata in the same way.