Unable to control OpenAPI operation ID with ApiExplorerSettings

[Steven Volckaert]

• NuGet Package Version: Ardalis.ApiEndpoints version 4.1.0
• .NET SDK Version: 7.0.306

I'm using Ardalis.ApiEndpoints version 4.1.0 in a new REST service - I've learned about the endpoint concept with your Clean Architecture Template and I quite like it.

My service targets net7.0 and has some endpoints for managing domains and websites of our CMS system:

There's also a StatusController which' abstract StatusControllerBase class it implements, is defined in a shared library (NuGet pacakge); this enables me to reuse its logic across all of our REST services (we have quite a few). So, StatusController implements Microsoft.AspNetCore.Mvc.ControllerBase.

As with most of our REST services, I create a client project (here Skarabee.CMS.AdminService.Clients) which contains generated code, generated by NSwag.MSBuild, and some custom code to make the library (which is distributed as a NuGet package) easier to use:

When building Skarabee.CMS.AdminService.Clients, NSwag.MSBuild will launch Skarabee.CMS.AdminService and use ApiExplorer to generate code (output goes to Skarabee.Cms.AdminService.Clients.g.cs).

By default, NSwag uses the OpenAPI operation ID to generate the names of the methods. Here it goes wrong: this is what the operations look like in Swagger UI 3:

I'm unable to group endpoints DisableRenewal, EnableRenewal under DomainEndpoints and CreateOrUpdate, Delete, DeleteBindings, ListBindings under WebsiteEndpoints.

I've tried setting the group name with [ApiExplorerSettings(GroupName = "DomainEndpoints")] on DisableRenewal endpoint class or on its HandleAsync method, but this has no effect.

Any idea what I might be doing wrong here?

Because I'm unable to control the group name / operation ID, the generated code in Skarabee.CMS.AdminService.Clients.g.cs returns unexpected results.

How can I control or set the OpenAPI operation ID?

Many thanks in advance for your help and insights!

Steven

PS In fact I'm looking for a standard way to create REST microservices; I'd like to develop a template (as in 'a pattern', not a VS/.NET template) that works for us and that we can use with all of our REST services (existing ones and new ones).

For this I've started with your Clean Architecture Template and eShopOnWeb, the latter which unfortunately seems to use something else than ardalis ApiEndoints; MinimalApi.Endpoint (although AuthenticateEndpoint is an Ardalis ApiEndpoint)

Recently, I discovered the updated Clean Architecture Template (I was using an older version apparently) is now using something called FastEndpoints.

So, I'm a bit lost in the many options that seem to exist nowadays to build an API in net6.0 / net7.0 / net8.0 (we prefer to stay on LTS releases), and I could use some guidance.

What would you recommend I use? Ardalis ApiEndoints or MinimalApi.Endpoint? Or FastEndpoints instead? Use Minimal API Results (Microsoft.AspNetCore.Http.Results) or Ardalis.Result?