如何设置 OpenAPI 重定向带有参数的响应？

Question

我有一个 HTTP 302（重定向），我实现了一个新的状态参数，该参数将附加到

RedirectURL

，因此可以显示类似的消息

如果调用 URL 传递为

GET http://localhost:8080/info/status?redirectUrl=http://localhost:8080/redirect

然后它将重定向为

http://localhost:8080/redirect?status=success

它的对应物

http://localhost:8080/redirect?status=error

但是 OpenAPI 规范中如何描述这一点呢？我似乎无法在响应中使用

parameters

并发现一些使用

responseParameters

的代码，但我没有运气让它工作......甚至不知道它是否是受支持的，至少，我用这两个命令编译都没有错误

  /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

出现这种情况的常见方式是什么？

我们是否应该有 2 个重定向 URL，例如

GET http://localhost:8080/info/status
   ?redirectUrl=http://localhost:8080/redirect
   &errorUrl=http://localhost:8080/redirect_error

我对这个简单的困境有点茫然，也许有人可以帮助😊

Answer 1

是的，这是 OpenAPI 的一个恼人的问题。您无法真正显式指定重定向。

您能做的最好的事情就是在 3xx 重定向范围（301、302、303、307、308）中指定带有状态代码的响应，该响应具有“string”类型的“location”标头参数。

然后您应该添加描述和摘要 - 几乎您已经完成了。

OpenAPI规范github中有这个问题：https://github.com/OAI/OpenAPI-Specification/issues/2512

希望尽快有所行动。

Answer 2

是的 openapi 不处理重定向（Arazzo 也不处理）。最近，当有人透露该项目的负责人不理解重定向

时，这是一个争论点