Path templating, multiple segments, and RFC 6570?

I’m trying to write swagger docs for APIs like dropbox where the number of path segments isn’t known ahead of time. For example, the path template will look something like:

/api/metadata/{filePath}

And the following urls should all match this path:

/api/metadata/file1.txt
/api/metadata/dir1/file2.txt
/api/metadata/dir1/dir2/file3.txt

If we were using RFC 6570, I’d represent this as:

/api/metadata/{/filePath*}

but the swagger v2 spec doesn’t say if this syntax is acceptable or not.

If it is acceptable/correct, could you please let me know in this item? If it’s not, what is the expected way to model APIs like this with runtime variable URI paths?

[sodiumjoe]

looks like it won’t be supported in 3.0

[emattheis]

Option 3 gets my vote.

I would argue that merging query params into the path template may make the overall specification simpler in light of #574 - the uniqueness of an operation could remain verb + path and satisfy the demands for including more variability if the path template had full RFC 6570 support.

Just to add a real-world use case for unescaped parameters: I maintain an API that represents a virtual filesystem with an endpoint /resources{+path} where the path variable represents the path of the resource (folder or file) in the virtual filesystem - e.g. /path/to/some/folder/ or /path/to/some/file.