Swagger: wildcard path parameters

Question

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 in Swagger?

We have the same issue - so far no luck! I'll update here if we find anything. — Rob Stevenson-Leggett, Mar 06 '17 at 20:17
Looks like this isn't supported in Swagger 2.0 (or even 3.0!) and there's a big discussion about why here: https://github.com/OAI/OpenAPI-Specification/issues/892#issuecomment-281170254 Seems silly as it seems really common to do this. — Rob Stevenson-Leggett, Mar 06 '17 at 20:25
I just noticed that you are the one that opened the issue I referenced! Haha — Rob Stevenson-Leggett, Mar 06 '17 at 20:40
Found a workaround which is acceptable for me, see my answer below. — Dmitry Frank, Mar 18 '17 at 21:30

score 13 · Accepted Answer · edited Jan 26 '22 at 10:42

This is not supported as of OpenAPI 3.1, and I have to resort to a workaround.

If I have a path /tags{tag_path} and I enter something like this as tag_path: /foo/bar, then the actual query request URL will be: /tags%2Ffoo%2Fbar. So, I just added support for that on my backend: the endpoint handler for /tags* urldecodes the path (which is %2Ffoo%2Fbar), and it becomes /foo/bar again.

Yes, a hack, but it works, and it's better than nothing. In my case, tag names can't contain the / character, so there's no conflict. Your mileage may vary, of course.

score 1 · Answer 2 · edited Nov 11 '22 at 07:18

If you are using a framework like Connexion, chances are it does support a wildcard path parameter (even though it is not in the OpenAPI spec).

Here is an example for Connexion.

paths:
  /pages/{path}:
    get:
     # (...)
      parameters:
        - name: "path"
          in: path
          description: "Remainder of path, including slashes."
          schema:
            type: string
            format: path

The difference is the format: path added.

Swagger: wildcard path parameters

2 Answers2

Linked

Related