Support for path parameters which can contain slashes

[dimonomid]

I see there are a few issues which ask for the opposite, e.g. this one https://github.com/swagger-api/swagger-js/pull/280 , but what I'm asking for is to add some option to the parameter, which would allow it to contain non-encoded slashes.

My use case: I have an API which allows any arbitrary path to be passed in, for example all of these:

• /api/tags
• /api/tags/foo
• /api/tags/foo/bar/baz

Are valid paths. I tried to describe it as follows:

  /tags{tag_path}:
    get:
      parameters:
        - name: tag_path
          in: path
          required: true
          type: string
          default: "/"

However, https://generator.swagger.io encodes slashes in the path, so it doesn't work. So is there a way to describe my API? It feels to me like a perfectly valid use case, so I'm surprised it's not supported.

If it's indeed not supported, then one possible solution is to add some option for the path parameter, which would allow it to contain non-encoded slashes.

What do you think?

[t1]

I'm not sure how GraphQL handles url path, last time I've checked - it doesn't.

GraphQL doesn't use paths. It's not based on resources, but more like RMI. Zealously mapping all operations to resources comes at a price.

[pkit]

GraphQL doesn't use paths. It's not based on resources, but more like RMI. Zealously mapping all operations to resources comes at a price.

Yeah, unless you're building an object storage and then "mapping to resources" is essentially the only thing you want. :)

[Joyce-Stack]

Just to contribute our own use case for this as its a problem for us at the moment.

We need to regularly support DOIs (https://www.doi.org/) which contain '/' as well as other characters. Here is an example - 10.1016/S0014-5793(01)03313-0

[nfroidure]

I'm not sure it is a good idea since it will make implementations harder but if it is added to the specs, the best fit for this use case would probably be to introduce a unique optional "rest" parameter that would have to be at the end of the path instead (like in JavaScript). It will preserve the possibility for frameworks to make optimizations (like segment based trees testing, see siso) instead of just test as much regular expression than defined routes.

Something like that could work, but the path templating is not required in fact:

  /tags{...tag_path}:
    get:
      restParameter:
        name: tag_path
        in: path
        required: true
        type: string
        default: "/"

[garymazz]

After nearly 6 years, it appears the OAI team has no interest or compunction to support this feature. There is a hack, but does not lend itself to an easily documented api. The OAI is more interested in some bizzare ideals of "specification purity" rather than making a complete, useful tool.

I, like others, have moved to GraphQl.

[afocus]

I need the same functionality too

[darrelmiller]

@Joyce-Stack If you are using a DOI as a path parameter then the slash in the DOI should be escaped as it is part of the data element, not part of the resource hierarchy. This is fully supported. It is the case where you people want the parameter to actually define the resource hierarchy that currently isn't supported directly.

[darrelmiller]

@garymazz Is there a problem with the extension solution that I suggested in July? Or is the problem that tooling hasn't implemented support for such an extension?

Also, the moonwalk proposal https://github.com/oai/moonwalk advocates for using for RFC 6570 URL templates, which would support multi segment paths.

I'm not exactly sure what you expect to gain from insulting the efforts of volunteers.

[betonetotbo]

Another good argument to support this is trying to answer this:

• How can I specify a proxy server using OpenAPI?

I have a scenario currently, that I created a microservice backend to handle presigned urls to give secure access to thirty-party integration to APIs that currently require authentication tokens. This are scenarios that the thirty-party software has not possibility to negotiate to obtain tokens.

So, in this case, I need to define an path like this:

• /presigned/{presignedAuthorizationHashKey}/*

The thirty-party will request something like: https://host.com/presigned/AS0DF90ASD9F0ASDDDAFFD/2232/details

[mimkorn]

I'd like to confirm if my understanding is correct that only server-side generation is issue from the practical point of view, not the spec itself.

I'm exploring an API design where a path parameter at the end of the URL can contain slashes, as illustrated below:

NodePath:
  name: path
  in: path
  required: true
  schema:
    type: string
  example: some/path/

We've implemented our server accordingly and observed that generated clients we tried handle these path parameters without issues, ensuring correct server responses. My understanding is that the challenge with slashes mainly pertains to server-side code generation, which we don't rely on.

Could someone confirm if there are other potential pitfalls with this approach, or if the concern is indeed primarily around server-side code generation? Maybe we'd have problems with linters/validators/mock servers/validation proxies, etc..?

The endpoint may look something like this: @Path("/tables/{table}/platform/{path:.*}")

The OpenAPI specification explicitly states that path parameters must not contain any unescaped "generic syntax" characters such as forward slashes (/), according to RFC3986​1​. But I'd like to know if we may encounter some issues I cannot forsee right now by deliberately ignoring it for this case.

Thank you for your insights!

[oyvindwe]

if the concern is indeed primarily around server-side code generation?

Client side code generation as well, for example API browsers as SwaggerUI. A / in the path parameter will be URL encoded in this case.

If you have control of the toolchain on both the client and server side, there is no problem, but if you want to leverage standard tool support you are in trouble.

[hunjixin]

also the same problem too. need feature like github /blob/{branch}/a/b/c/d.go. any plan for this issue?

[Nikoolayy1]

It seems like /niki/{test+} or /niki/{test++} or /niki. or /niki/{test=} or /niki/{test=**} are vendor specific workarounds for wildcard urls for the openapi specification and some vendors support this, some don't and we are still waiting this to be added to the official Openapi spec.

[pkit]

@Nikoolayy1 which vendors though? Lol So far I haven't found any support anywhere.

[Nikoolayy1]

@pkit F5 BIG-IP AWAF/ASM supports wildcard url in a Openapi/Swagger https://community.f5.com/t5/technical-forum/f5-awaf-asm-support-for-wildcard-url-and-parameter-names-with-a/td-p/322207 in the form of "/{path=**}": . Also here https://stackoverflow.com/questions/42335178/swagger-wildcard-path-parameters Connexion is mentioned.

[handrews]

This has been rolled up into #2653, which in turn will almost certainly be moved over to the Moonwalk (OAS 4) project, which as currently proposed supports full RFC 6570 URI Templates.

[garymazz]

@handrews
Thank you for doing this work moving it over to Moonwalk !! Is there a initiative for a POC for this feature or is this waiting to the specification update, as I've been told previously ? How/who is coordinating the implementations between the parser and the generators ?

[handrews]

@garymazz we're not quite to that point with Moonwalk, although we have set an aggressive schedule to release it by the end of 2024. The Moonwalk-specific community calls will be starting at 9AM US-Pacific time on Tuesdays (I think this coming Tuesday will be the first one). We'll be working out details there.

[garymazz]

@handrews Thank you for the quick reply. This new work is timely, I'm starting to implement a new, open source version of SNIA CDMI ISO standard. See: https://www.snia.org/cloud/cdmi#:~:text=CDMI%20is%20an%20open%20international,that%20is%20placed%20in%20them.

I would like to use Moonwalk for the server side implementation (C language). I'll try to attend the meetings, I do have another standards meeting conflicting with your 0900/9am PST, I'm trying to resolve. I'll definitely be on upcoming meeting.

[handrews]

@garymazz we're talking about having some alternative time slots, for time zone coverage among other things. If you're not on our Slack you can join using the link in the "Participate" menu on the main OpenAPI web site. The spec and sig-moonwalk channels will be the ones you want in addition to general in order to get updates on this stuff.

[garymazz]

@handrews Thanks, just joined. # spec is a default channel. # sig-moonwalk needs to be manually added.