Invalid API path parameter

[bcronin90]

There's currently an issue with the dataplane API in that it is not compliant with OpenAPI v3:
https://app.swaggerhub.com/apis/eclipse-edc-bot/control-api/0.0.1-SNAPSHOT

I realize why the {any} path parameter is there, but the way it's used right now is not ideal. There's a few ways we could go about this and I'd like some input:

1. Remove the path parameter, as it is used only to forward a call to any path to this API. This would be my preferred approach.
2. Use the path parameter to resolve the source data address if this cannot be done via the token (not sure if this makes sense though).
3. Leave the parameter, but don't use it. (This draft PR fix: Add PathParam #3369, also not ideal as it does not conform to the coding style.)

@ndr-brt

[bcronin90]

Alternatively, this might be solvable with an annotation, which of course would be ideal. I'll look into it.

[ndr-brt]

One issue that I see here is that the data-plane public api should not be under the "control-api", because it's not an internal api meant to be used in the intra-connector communication but it is a public endpoint, in fact it is exposed on the "public" context, it should end up into a dedicated openapi spec file. wdyt @paullatzelsperger ?

@bcronin90 Could you describe what's the specific problem with this?
There is some interesting discussion on the openapi repository.

[paullatzelsperger]

Yep, I agree with the DP public API being put under its own "api group"

[bcronin90]

The problem is that it is currently under the path /{any:.*}, which can match to any path. But to OpenAPI, this anyis an undefined path parameter. And that makes our OpenAPI doc invalid. We have a similar issue downstream and it's harder to solve than it has any right to be.

I've seen the talk about slashes, but I don't think it applies here.

[paullatzelsperger]

From what I could gather in a quick search, OpenAPI 3 does not support wildcard path parameters. So actually, the problem is not specifically the any term, but the wildcard path param (.*). The way I understand it any doesn't have a special meaning, it's only a path variable.

[bcronin90]

Yeah, "any" here is just a name. You're right, from what I can tell, any wildcard is not allowed under OpenAPI 3.0/3.1. How do we deal with that? It seems we don't actually use these wildcard parameters other than to allow for any URL path to reach the API.

[paullatzelsperger]

not sure there is all that much we can actually do here, other than possibly moving the Dataplane Public API into its own yaml file, so that is doesn't "pollute" the other yamls.

[bcronin90]

In that case I'll just have to work around it. But it's kinda annoying not to be OpenAPI compliant. I'll close the draft PR and find another way.