Manually set operationId to allow multiple operations with the same verb in Swashbuckle

Question

I need to know if it's possible to set up custom operationid, or a naming convention, I mean I know that operation filter can be overwritten the way how operationId is generated

https://azure.microsoft.com/en-us/documentation/articles/app-service-api-dotnet-swashbuckle-customize/

using Swashbuckle.Swagger;
using System.Web.Http.Description;

namespace Something
{
    public class MultipleOperationsWithSameVerbFilter : IOperationFilter
    {
        public void Apply(
            Operation operation,
            SchemaRegistry schemaRegistry,
            ApiDescription apiDescription)
        {
            if (operation.parameters != null)
            {
                operation.operationId += "By";
                foreach (var parm in operation.parameters)
                {
                    operation.operationId += string.Format("{0}",parm.name);
                }
            }
        }
    }
}

in SwaggerConfig.cs

 c.OperationFilter<MultipleOperationsWithSameVerbFilter>();

Now this is helpful transforming swagger description, check bellow:

All good, now I endup with another problem, example similar with may cases: on same controller I have two endpoints

• Post: /customer boddy: {email, location....}
• Post: /customer/search boddy: {a filter, whatever}

The example is not quite correct (last post should be a get) but still le assume that webapi cannot be changed (new controller for separation) for this particular case I will try to figure out a way to generate operationId diffrent for each action somehow, but my question is this:

Is it possible to decorate somehow the controller actions similar with [JsonIgnore] or with [Route("customer/delete")], to be explicit about the operationId.

Solution 1

EDIT This answer relates to Swashbuckle 5.6 and .NET Framework. Please read mwilson's answer for Swashbuckle and .NET Core

You can use the SwaggerOperationAttribute provided by Swashbuckle for that.

[SwaggerOperation("get")]
public IEnumerable<Contact> Get()
{
    ....
}

[SwaggerOperation("getById")]
public IEnumerable<Contact> Get(string id)
{
    ...
}

You can use that attribute to add tags and schemes to your operation as well by the way. Have a look at the source code

Solution 2

For swashbuckle 5.0, you can use the Name attribute. You can set it to any string but I'm a fan of using nameof like this: nameof(ActualMethodName).

[HttpGet("{id:int}", Name = nameof(GetProductById))]
public IActionResult GetProductById(int id) // operationId = "GetProductById"'

or

[HttpGet("{id:int}", Name = "GetProductById")]
public IActionResult GetProductById(int id) // operationId = "GetProductById"'

There are a few other options listed here

Comments

[aruno]

Shouldn't this be "Contact_get" and "Contact_getById"?

[Olavi Vaino]

For some reason [SwaggerOperation("operationId")] didn't work in our case. Using .Net Core 3.1 and swashbuckle 5.6.0. However [HttpGet(Name = "operationId")] works.

[apincik]

You have to set OperationId property, [SwaggerOperation(OperationId = "MyCustomName")] , NetCore 3.1, swash* 5.2.x

[Perrier]

You can use [action] and [controller] variables here, too. eg: [HttpGet(Name = "[controller]_[action]")] produces Contact_Get on the HttpGet method of ContactController.

[David Keaveny]

@Simon_Weaver Visual Studio's Connected Services feature will choke on operation IDs if they contain underscores (see stackoverflow.com/questions/68166935/…)