OpenAPI: merge multiple body content types into one operation

[ascott18]

OpenAPI: merge multiple body content types for the same path/method

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Description

This change merges multiple body content types into one operation definition in the OpenAPI document when there are multiple endpoints with the same path and HTTP method but different Consumes attributes.

The previous behavior would clobber existing operations in this scenario such that the last defined operation wins.

Fixes #58329

[captainsafia]

Thanks for the contribution! Comment left inline.

[captainsafia]

This logic looks great overall! However, I believe we want to apply this before operation transformers are applied so that transformers registered by the user get the correct view.

I'm reviewing this on mobile so if this is already the case and I missed it let me know.

Also, we might want to add a test case to verify that transformers see the correct data.

[ascott18]

@captainsafia Thank you for the review. I made some adjustments to better support operation transformers.

Your comments made me realize that with my original changes, the transformer would run multiple times for a given operation, once per ApiDescription. I've adjusted it to perform grouping and merging before the transformers runs for the operation. I added a property AllDescriptions to the transformer context so that the transformer implementation can receive all descriptions that were merged together. The existing Description property on the context is unchanged so that this isn't a breaking change - it holds the first ApiDescription in the group.

This should eliminate any possible breakage caused by this change - I'd imagine there are users whose operation transformers are not expecting to be run multiple times on one operation.

I had to make a slight adjustment to XmlController so that Get1 is now a distinct route from Get, since these two actions are testing different parts of the XML comment logic. Since the logic is now that first wins instead of last wins, there was a change to the snapshots.

My gut is that this change from last-wins to first-wins isn't a major problem in terms of breaking changes, but if it is a problem, I can change the merging logic to preserve the old behavior where the last declared endpoint is the primary source of information for a give path + method combination, instead of the first declared endpoint.

[mikekistler]

I thought that having multiple endpoints with the same route and verb triggered analyzer warnings. Is that not the case or are these being suppressed for this use case?

Also, I want to note ... in the related issue there is this statement:

A single route can indeed support both formdata and json bodies.
That may be true, and there is a way to express this in OpenAPI v3.x, but OpenAPI v2 forbids this:
Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.

I'm curious how this change will affect the generated OpenAPI if the app specifies that it should be OpenAPI v2.

[ascott18]

I'll investigate the impact on v2 - thanks for identifying that.

The analyzer doesn't trigger in this case because ConsumesAttribute is not one of the listed attributes that doesn't affect route matching (rightfully so, because it does affect route matching by its implementation of IActionConstraint.)

aspnetcore/src/Framework/AspNetCoreAnalyzers/src/Analyzers/Mvc/DetectAmbiguousActionRoutes.cs

Line 168 in 5d0e3b0

private static readonly WellKnownType[] KnownMethodAttributeTypes = new[]

[ascott18]

It looks like for v2, the following happens:

• If one of the bodies is form data, then it always wins, regardless of declared/discovered order of endpoints. No in: body parameters are emitted.
• If both of the bodies are from body but have different types (i.e. XML and JSON, with different CLR body types), the first declared endpoint wins, and the second one is ignored.

So, it at least seems that Microsoft.OpenApi already handles this as elegantly as it can within the constraints of what OpenAPI v2 allows. It doesn't throw exceptions or produce invalid output.

[Copilot]

Pull Request Overview

This PR enables merging multiple body content types into a single OpenAPI operation when multiple endpoints share the same path and HTTP method but have different [Consumes] attributes. Previously, the last defined operation would overwrite earlier ones, resulting in lost content type definitions.

Key changes:

• Modified OpenAPI document generation to group endpoints by HTTP method and merge their request body content types
• Enhanced the operation transformer context to include all merged endpoint descriptions
• Updated test cases to verify the merging behavior and transformer execution

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
OpenApiDocumentService.cs	Core logic to group endpoints by HTTP method and merge request body content types
OpenApiOperationTransformerContext.cs	Added AllDescriptions property to expose all merged endpoint descriptions
OperationTransformerTests.cs	Added test verifying transformers execute once per merged operation set
OpenApiDocumentServiceTests.RequestBody.cs	Added test for multiple content type merging behavior
XmlController.cs	Updated route template from query parameter to path parameter
Snapshot files	Updated test snapshots reflecting the route template change
PublicAPI.Unshipped.txt	Added new public API surface for AllDescriptions property