Documentation leads me to believe all UmbracoApiControllers will just "show up" in Swagger

[markadrake]

Link to Umbraco Documentation:

• API Controllers
• API Versioning

I followed the instructions to create my own API controllers. It's not something I often do so I prefer to have the latest and greatest documentation open at all times. I was under the impression that any UmbracoApiController class not mapped to a specific Swagger document would be magically included on the list. But that's not so.

If you do not attribute your UmbracoApiController class with [ApiController], and the mandatory [Route()], your controller and methods will not show up in Swagger. Maybe everyone knows this, but I feel like the documentation should be written to a level that following the examples will just work.

I'm starting this as a discussion because my comfort level with C# and backend programming isn't enough to "know that I'm right".
All I do know is that Swagger did not care for my API endpoint(s) until they were annotated.

[nikcio]

Hey @markadrake

I can add some insight here. Umbraco uses the .AddApiExplorer() and .AddControllers (Code search) to register what controllers and API controllers exist in the Asp Net Core application it's therefore not Umbraco directly registering what controllers are registered in the Swagger documentation. Therefore for an endpoint to show up you need to create an endpoint that will be noticed by these default Asp Net Core components.

Umbraco-CMS/src/Umbraco.Web.Common/DependencyInjection/UmbracoBuilderExtensions.cs

Line 265 in 98e9a30

builder.Services.AddApiVersioning().AddApiExplorer();

So works something like this:

Your project --> Reference to Umbraco --> Umbraco registers .AddControllers and .AddApiExplorer --> Umbraco registers swagger --> Swagger pulls the information on what endpoints exists from what is registered by .AddControllers and .AddApiExplorer. --> Swagger generates the documentation.

Therefore as you pointed out you need the [Route("")] attribute for it to be picked up. Now I didn't test this when writing but I think you don't nesserayly need the [ApiController] attribute for an endpoint to be picked up in the documentation but that just enables some other things described here: https://stackoverflow.com/questions/66545845/what-does-the-apicontroller-attribute-do

But you will also notice that if you create a minimal API endpoint Example this also wouldn't be picked up in Swagger. This is because Umbraco is missing a call to .AddEndpointsApiExplorer() on the service collection so this will need to be added before these will show up and there also need to be made a change in the swagger options. I made a PR for this a while back but totally forgot about it: #15383

That's my understanding of how it works at least hope it helps answer your question.

[c9mb]

Just starting to look at this general topic of implementing a custom REST API, and note that UmbracoApiController was obsoleted in v14 and removed in v15.

The recommended solution is to implement a native Controller, but (and without giving it much investigation) I'm wondering if/how it might be possible to implement custom REST APIs using the DotNet Minimal API model ?