ardalis / ardalis/ApiEndpoints

Unable to control OpenAPI operation ID with ApiExplorerSettings

Open
#197 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
3.2k
Forks
232
PR merge metrics
No merged PRs in 30d

Description

- 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:

![image](https://github.com/ardalis/ApiEndpoints/assets/9107183/65153813-3944-4b21-b9a3-cb7c0f009c77)

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:

![image](https://github.com/ardalis/ApiEndpoints/assets/9107183/a708a534-46cc-4ba2-be66-4b801bd6c554)

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:

![image](https://github.com/ardalis/ApiEndpoints/assets/9107183/2a22c930-5cb7-4e2e-ab71-7ba9a44f8e37)

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](https://github.com/dotnet-architecture/eShopOnWeb/blob/main/src/PublicApi/AuthEndpoints/AuthenticateEndpoint.cs) 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?

Contributor guide

Open the contributing guide

Research direction

Start by reading the DisableRenewal and EnableRenewal endpoint classes, their HandleAsync methods, and the StatusController, then compare ApiExplorer output in Swagger UI with Skarabee.Cms.AdminService.Clients.g.cs. Done means the requested DomainEndpoints and WebsiteEndpoints grouping or operation IDs are reflected in the generated client method names.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.