Support configuring document-level parts of OpenAPI schema

[captainsafia]

Starting in .NET 7, we added support for a WithOpenApi extension method on endpoints that allowed users to modify the OpenApiOperation associated with a particular endpoint. For example, we can modify the summary of an OpenApi Operation associated with an endpoint using the following.

app.MapGet("/foo/bar", () => ...)
  .WithOpenApi(operation =>
  {
    operation.Summary = "Just a sample endpoint";
  });

However, this API has a major limitation: it doesn't allow modifying aspects of the OpenAPI definition that exist at the document-level. This includes things like:

• Setting tags on an application document
• Setting security schemes associated with an application (especially relevant for Automatically infer OpenApiSecuritySchemes from authentication configuration #39761)
• Setting summary and description for an entire document
• Modifying a path (which maps to a route group in minimal APIs)

IMO, a super ✨ amazing ✨ experience would be supporting a WithOpenApi extension method directly on the WebApplication so that users could modify the OpenApiDocument associated with their application:

app.WithOpenApi(document =>
{
  document.Tags = ["this", "is", "some", "tags"];
});

One thing to note here, is how the app-level WithOpenApi and the endpoint-specific WithOpenApi will interact with each other. If I'm operating on the app-level WithOpenApi, can I modify operation-level details that can then be examined within an application?

If this was the case, we'd probably want there to be an OpenApiDocument in DI that is projected upon from the WithOpenApi extension methods targeting each endpoint/endpoint group/document.

While writing this issue, I came across microsoft/OpenAPI.NET#673, which proposes a builder-style syntax for building an OpenAPI document. This would be a great feature to add into the application.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[captainsafia]

This is done now with our new built-in support for OpenAPI in .NET 9.