Content Delivery API - API non compliant to Swagger Spec

[vsilvar]

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

12.0.0-rc2

Bug summary

The OpenAPI v3 specification does not support path parameters with multiple segments (OAI/OpenAPI-Specification#892).

This means that any OpenApi tooling won't support it either, and will simply encode the slashes when doing API requests.
This can already be seen in the swagger UI itself, which means you get a 404 when trying to, for example, retrieve the root /

In order for Umbraco to have a compliant spec and allow consumers to use code generation tools, I think it should support both encoded and non-encoded paths.

Specifics

No response

Steps to reproduce

1. Install the latest Umbraco 12 RC2
2. Create some dummy content types and content
3. Use the swagger UI to retrieve content by path / or configure a code generation tool by following the following steps
4. Save the /umbraco/swagger/delivery/swagger.json file in the project as UmbracoDeliveryApiSwagger.json
5. Add the following to the .csproj file:

<ItemGroup>
 <PackageReference Include="NSwag.ApiDescription.Client" Version="13.19.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 </PackageReference>
 <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
 <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="7.0.5">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 </PackageReference>
 <OpenApiReference Include="UmbracoDeliveryApiSwagger.json" CodeGenerator="NSwagCSharp" Namespace="Umbraco.DeliveryApi" ClassName="DeliveryApiClient" />
</ItemGroup>

6. Add the following to the end of WithEndpoints in Startup.cs:

u.EndpointRouteBuilder.MapGet("/delivery-test", async (HttpContext context, IOptions<WebRoutingSettings> webRoutingSettings, IHttpClientFactory httpClientFactory) =>
{
    DeliveryApiClient client = new(context.Request.GetApplicationUri(webRoutingSettings.Value).ToString(), httpClientFactory.CreateClient(nameof(DeliveryApiClient)));

    return await client.GetContentItemByPathAsync("/");
});

7. When you call the /delivery-test endpoint you'll get an exception due to the 404

Expected result / actual result

No response

[github-actions]

Hi there @vsilvar!

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

[vsilvar]

#14298 is related to this issue.

Also, interestingly enough, if backslashes are used instead of forward slashes, then it works.

[kjac]

Hi @vsilvar,

Thank you for testing the RC 🚀 looks like you're giving it a good spin, which is exactly what we hoped for 😄

The OpenAPI 3.0 specifications does actually allow for forward slashes in parameters - here's a bit from the serialization part of the specification:

Swagger UI on the other hand is not entirely playing nice for us at the moment. As mentioned on #14298 we are looking into this. Worst case we'll end up having to remove the endpoint from Swagger, which is really not optimal at all.

While this certainly sounds like the same issue as #14298, could I ask you to verify that by checking if the client indeed URL encodes the forward slashes?

[vsilvar]

Hi @kjac

Indeed, the issue is the encoding, as you can see by the generated code:

The snippet you are mentioning, as I interpret it, only seems to apply to query parameters, and not path parameters.
I'm not totally sure my interpretation is correct, but it seems to align with the schema:

[kjac]

Hi again @vsilvar,

Thanks for investigating, I really appreciate you taking the time 🥇

I'm going to keep this issue open for now, even though technically it is a duplicate of #14298 ... we'll make sure to update both issues when we know more.

[kjac]

Fixed in #14311

See also #14298 (comment)

[kjac]

#14311 has been merged now, so I'll go ahead and close this issue.

We are looking into a V12 RC3, which will contain this fix. It is still unknown when it will be out, we have a few more things we'd like in there.

Again, thank you so much for bringing this issue to our attention 👍