CQRS Expose as endpoint - operation name

[shainegordon]

What problem are you trying to solve?

A lot of tools that create API clients from Swagger Open API specification files use the "operationId" field to build human-readable functions/methods.

Because no operationId is defined by default, swagger (and code gen tools) will do a best effort to infer these names.

So, for example, the command DeletePriceCommand would result in the inferred name of delete_api_price__id_, while the API client generation tool might then create a function called priceDELETE (this depends on how the tool is configured).

Describe the solution you'd like

We would like API routes to be "named"

so instead of the following being generated (I have removed some attributes for brevity)

[HttpDelete("api/price/{id}")]
public async Task<ActionResult> DeletePrice([FromRoute] Guid id, CancellationToken cancellationToken = default)
{
       await _mediator.Send(new DeletePriceCommand(id: id), cancellationToken);
       return Ok();
}

it would be nice if instead it was generated as follows

[HttpDelete("api/price/{id}", Name="DeletePrice[Command]")] // I've put "Command" here as optional, but I think it sometimes is very useful to know what is a query/command, as it gives additional context with regard to if side effects we be performed.
public async Task<ActionResult> DeletePrice([FromRoute] Guid id, CancellationToken cancellationToken = default)
{
       await _mediator.Send(new DeletePriceCommand(id: id), cancellationToken);
       return Ok();
}

Notice that all that has changed here is I have added the Name parameter to the HttpDelete/Get/Put/Post attribute.

This then gives you a "better" experience in swagger UI

and your API client makes more sense

api.DeletePriceCommand(priceId)

[JonathanLydall]

Hi @shainegordon,

Thanks very much for this suggestion, it appears to make perfect sense to add to our standard modules, I've added this to our backlog.

I'll leave this issue open until this improvement is finalized so as to provide updates.

[JonathanLydall]

Hi @shainegordon,

We have now completed the work for this, basic information on this is available here, but at a high level you can now apply an OpenAPI Settings stereotype on which you can specify the an operationId:

You will just need to make sure you have the latest pre-release versions of the Intent.Metadata.WebApi and Intent.AspNetCore.Controllers modules installed.

We expect to be publishing the final versions of these modules next week.

I'm closing this issue, but feel to ask any further questions you may have.