Umbraco Delivery API not valid OpenAPI specification (according to APIM)

[RBerntsen]

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

14.3.0

Bug summary

When we try to import the JSON specification for the API's from Swagger (out of the box on v14) into Azure API Management, we get two errors:

1. The security scheme "Backoffice User" is invalid (cannot have a space)
   

2. Four operations with duplicate signatures:
   

This is due to the fact that we have four pairs of endpoints that are somewhat equal, only difference is the name of the parameter, i.e. "path" and "id" are both of type string.

The endpoints are these four pairs:

/umbraco/delivery/api/v1/content/item/{path}
/umbraco/delivery/api/v1/content/item/{id}

/umbraco/delivery/api/v2/content/item/{path}
/umbraco/delivery/api/v2/content/item/{id}

/umbraco/delivery/api/v1/media/item/{path}
/umbraco/delivery/api/v1/media/item/{id}

/umbraco/delivery/api/v2/media/item/{path}
/umbraco/delivery/api/v2/media/item/{id}

I think it would be relatively easy to rename the scheme for the "Backoffice User" to e.g. "BackofficeUser" as that looks to just be a const string:

I'm unsure how exactly to handle the issue with the duplicate endpoints, as we would probably like both to be displayed in Swagger?

I have encountered similar issues on v12 and v13 as well.

Specifics

See above

Steps to reproduce

Navigate to your APIM instance in Azure.
Select "APIs" and select "OpenAPI" under the "Create from definition".

From here you can upload the JSON file that was generated for the Swagger documentation.

When doing this you will first be presented with the error for the security scheme. After fixing that you will be presented with the issue for the duplicate endpoints.

Expected result / actual result

I would expect that the JSON file contained a valid OpenAPI specification that could be imported into APIM without modifications

---

This item has been added to our backlog AB#45094

[github-actions]

Hi there @RBerntsen!

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 🤖 🙂

[iOvergaard]

Hi @RBerntsen, thanks for the report. We will take a look at it in an upcoming sprint!

[kjac]

Hi @RBerntsen,

Thanks for reporting! The Delivery API OpenAPI spec should not have the Management API security scheme to begin with 🙈

#17401 fixes the validation errors of the spec.

Do note that the "duplicate signatures" issue you're encountering is not caused by an invalid OpenAPI spec. The spec has explicit and unique operation IDs for each endpoint 👍

[elit0451]

Fixed in #17401