How does one setup OpenAPI redirect response with parameters?

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.