I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:

[cobertvc]

I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:

/api?action=action1&some-param=1
/api?action=action2&other-aparam=2

If I would put all parameters under a single path, that would force all parameters under that path, too and would mix a lot of parameters that are only valid on certain actions.

The Swagger editor doesn't let me create multiple entries for the same path, even if the action parameter is required with a different value on each. and doesn't accept /api?action=action1 as a separate path either.

Is the unique path a requirement from Swagger or from the OpenAPI spec ?

Is there a good workaround how to handle this ?

Thanks!

Originally posted by @willamowius in https://github.com/OAI/OpenAPI-Specification/discussions/3344

[whitlockjc]

In your examples, the path is identical because the path portion of the API is /api. This is why we don't support a "path" as being a combination of path and query parameters. This is an OpenAPI rule. As for how you can handle this, you could have a single /api path and use the path-level parameters to document action and the other parameters. I'm sure you're wanting to document a certain combination of parameters as a single "API" but that isn't support in OpenAPI right now (parameter dependencies) and this is documented here: https://swagger.io/docs/specification/describing-parameters/#dependencies