Management API specific swagger config affecting other APIs (e.g. Content Delivery API)

lauraneto commented 3 months ago

Which Umbraco version are you using? (Please write the exact version, example: 10.1.0)

14.0.0

Bug summary

For V14, some adjustments were made to the Swagger configuration to support the Management API. Unfortunately, some of these settings are being applied globally when they should be scoped to the Management API swagger document.

A clear example of this going wrong is the security scheme, where it shows the Management API authentication in the Content Delivery API swagger.

While there are different files to configure the SwaggerGen options for the Delivery API and the Management API, there doesn't appear to be actual logic to only apply the changes to the respective swagger documents.

Specifics

No response

Steps to reproduce

Set up a new Umbraco project in V14, run it and access the Delivery API swagger in /umbraco/swagger/index.html?urls.primaryName=Umbraco+Delivery+API or /umbraco/swagger/delivery/swagger.json.

Notice that the Authorization (Security Scheme) is configured as the Management API one, which is not relevant for this API. You can also compare the result of /umbraco/swagger/delivery/swagger.json from a V13 and a V14 instance.

Expected result / actual result

Configurations specific to the Management API or Content Delivery API should not be applied globally and affect each other or other APIs, or at the very least, configuration that should apply to to all should move to a central place, so it's clear.

This item has been added to our backlog AB#41957

github-actions[bot] commented 3 months ago

Hi there @lauraneto!

Firstly, a big thank you for raising this issue. Every piece of feedback we receive helps us to make Umbraco better.

We really appreciate your patience while we wait for our team to have a look at this but we wanted to let you know that we see this and share with you the plan for what comes next.

We'll assess whether this issue relates to something that has already been fixed in a later version of the release that it has been raised for.
If it's a bug, is it related to a release that we are actively supporting or is it related to a release that's in the end-of-life or security-only phase?
We'll replicate the issue to ensure that the problem is as described.
We'll decide whether the behavior is an issue or if the behavior is intended.

We wish we could work with everyone directly and assess your issue immediately but we're in the fortunate position of having lots of contributions to work with and only a few humans who are able to do it. We are making progress though and in the meantime, we will keep you in the loop and let you know when we have any questions.

Thanks, from your friendly Umbraco GitHub bot :robot: :slightly_smiling_face:

kjac commented 1 month ago

Hi @lauraneto,

Thanks for reaching out 👍

Unfortunately, Swagger UI only allows for a global default OAuth client ID. In fact, the OAuth configuration as a whole (e.g. available security schemes, or whether to use PKCE for Authorization Code Flow) seems to be global in Swagger UI.

We have chosen to use the Management API client ID over the Delivery API client ID for a few reasons:

We assume Swagger will be used a lot more for Management API experiments than Delivery API ones.
We also can't setup a default auth scheme for the Delivery API, since it requires a lot of moving parts (a member login implementation among other things). But if you set it all up according to the docs article, the Swagger UI will show both Management API and Delivery API auth options:

As you can see, Swagger UI applies umbraco-swagger as default client ID, because it's a global configuration 😢 but (again as per the docs article), you can change it to umbraco-member to test member auth in the Delivery API.

If you really really want to, you might be able to configure an additional Swagger UI on an alternative route, and include the Delivery API as an explicit Swagger Document with a custom auth configuration. I wouldn't recommend it, though, as it's not something we'll be supporting actively.

umbraco / Umbraco-CMS