ApiExplorer not handling multiple routes on same action method correctly

[domaindrivendev]

Describe the bug

Given the following action method bound to multiple routes:

[HttpGet]
[Route("foo")]
[Route("bar/{id}")]
public IActionResult Get(int id = 0)

As expected, the ApiExplorer surfaces two ApiDescription instances, one for each route. However, for the first route "foo", the ApiDescription includes the id path parameter, despite the fact that it's not part of the route template. For example, here's the ApiExplorer data (serialized as json):

[
  {
    relativePath: "Test/foo",
    httpMethod: "GET",
    parameters: [
      {
        name: "id",
        source: {
          displayName: "Path",
          id: "Path",
          isGreedy: false,
          isFromRequest: true,
        },
      }
    ],
  },
  {
    relativePath: "Test/bar/{id}",
    httpMethod: "GET",
    parameters: [
      {
        name: "id",
        source: {
          displayName: "Path",
          id: "Path",
          isGreedy: false,
          isFromRequest: true,
        },
      }
    ],
  },
]

To Reproduce

> git clone [email protected]:domaindrivendev/ApiExplorerIssue.git
> cd ApiExplorerIssue
> dotnet run

Then navigate to "http://localhost:5000/apidescriptions" to see the ApiExplorer data

Further technical details

• ASP.NET Core version: 3.1

[domaindrivendev]

Here's the corresponding downstream issue that was originally created in Swashbuckle.AspNetCore:
domaindrivendev/Swashbuckle.AspNetCore#1834

[domaindrivendev]

In the meantime, if you're really stuck you could wire up an IOperationFilter (see readme) that detects this anomaly and corrects it by removing the parameter from the operation.parameters collection.

[frankracis-work]

I had the filter look at ApiDescription.ParamaterDescriptions, and if In==Path and !IsRequired, removed it from the operation.Parameters list. I don't know that this will work for every case, but it was enough for my routes.

[ghost]

Thanks for contacting us.
We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[ghost]

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[brunolins16]

@domaindrivendev the short answer for that is, you could workaround it by setting ApiBehaviorOptions.SuppressInferBindingSourcesForParameters to true. Eg.:

builder.Services.Configure<ApiBehaviorOptions>(options => {
    options.SuppressInferBindingSourcesForParameters = true;
});

Now, to give you more details. When your controller is annotated with [ApiController] it will be applied some conventions and one of them is the InferParameterBindingInfoConvention that will basically do what is described here ApiBehaviorOptions.SuppressInferBindingSourcesForParameters Property

As you can see, in your case you do have a route where the parameter is included in the route, that means this parameter will be inferred as Binding from Path and that will affect how Swashbuckle deal with the route and setting both as FromPath and Required.

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/45875d5e222f9f7369b6e5f31e1ece112fa81aaa/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/ApiParameterDescriptionExtensions.cs#L23

Once you have the property SuppressInferBindingSourcesForParameters set as true the binding source will not be inferred and you will have the behavior that you are looking for:

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPISample",
    "version": "1.0"
  },
  "paths": {
    "/WeatherForecast/foo": {
      "get": {
        "tags": [
          "WeatherForecast"
        ],
        "operationId": "Foo",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/WeatherForecast/bar/{id}": {
      "get": {
        "tags": [
          "WeatherForecast"
        ],
        "operationId": "Bar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": { }
}

Just remind that it is a global configuration that will affect all API controllers that might cause some issues to your current APIs.

[brunolins16]

@domaindrivendev In addition to my previous comment, it is a bug and it should be work correct without you need to change the SuppressInferBindingSourcesForParameters but while we do not have a fix, that is the option other than the option you mentioned about IOperationFilter

[halter73]

Once you have the property SuppressInferBindingSourcesForParameters set as true the binding source will not be inferred and you will have the behavior that you are looking for

Doesn't this change the actual behavior of the controller and not just the ApiExplorer model? Based on the linked docs, I would expect that the id parameter would no longer be inferred to come from the path in the "/WeatherForecast/bar/{id}" case (although the swagger indicates otherwise). Do you have to use param attributes after setting SuppressInferBindingSourcesForParameters to true?

[brunolins16]

Doesn't this change the actual behavior of the controller and not just the ApiExplorer model? Based on the linked docs, I would expect that the id parameter would no longer be inferred to come from the path in the "/WeatherForecast/bar/{id}" case (although the swagger indicates otherwise). Do you have to use param attributes after setting SuppressInferBindingSourcesForParameters to true?

@halter73, exactly that is why I included a small disclaimer (below) at the end. However, I tested it and the parameter binding still working, without adding the attributes, for me but I did not check exactly why.