How does one setup OpenAPI redirect response with parameters? - redirect

Question

I have an HTTP 302 (Redirect) that I implemented a new status parameter, that will append to the RedirectURL, so one can show a message something like
if the call URL is passed as
GET http://localhost:8080/info/status?redirectUrl=http://localhost:8080/redirect
then it will redirect as
http://localhost:8080/redirect?status=success
and it's counterpart
http://localhost:8080/redirect?status=error
but how does one describe this in OpenAPI specification? I can't seem to make use of parameters in the response and found some code that uses responseParameters but I had no luck to make it work... don't even know if it's something that is supported, at least, I get no errors compiling with both commands
/info/setup:
get:
summary: Setup Url
description: Setup Url to create new setup. Should be retrieved from api
apps endpoint and redirect to, not called directly by the url defined
here
parameters:
- in: query
name: installationId
description: The installation id
required: true
schema:
type: string
- in: query
name: redirectUrl
description: Url to redirect back to upon finished installation
required: true
schema:
type: string
responses:
"302":
description: Redirect
responseParameters:
- in: query
name: status
description: the status of the instalation
schema:
oneOf:
- type: string
example: success
description: When the installation was successful
- type: string
example: error
description: When the installation was erroneous
headers:
location:
description: Setup state based redirect
schema:
oneOf:
- type: string
description: If setup is done and valid for installation id, will
redirect to given redirect url
- type: string
description: If no setup exist for installation id, will redirect to
SumUp oauth page
- type: string
description: If error during authorization with SumUpl, e.g. non
matching editions, will redirect to a setup page for
further user action
what is the common way of having such a scenario?
should we have 2 redirect URLs like
GET http://localhost:8080/info/status
?redirectUrl=http://localhost:8080/redirect
&errorUrl=http://localhost:8080/redirect_error
I'm a bit of a loss on this simple predicament, maybe someone can help 😊

Answer 1

Yes, this is an annoying issue with OpenAPI. You cannot really specify a redirect explicitly.
The best you can do is specify a response with a status code in the 3xx redirect range (301, 302, 303, 307, 308) that has a "location" header parameter of type "string".
You should then add a description and summary - pretty much what you have already done.
There is this issue in the OpenAPI specification github: https://github.com/OAI/OpenAPI-Specification/issues/2512
Hopefully something will be done soonish.