Swagger 相同的路径指定了两次

Question

在 Swagger-UI 渲染的一个 API 规范中是否可以多次出现相同的路径？

我是否应该创建单独的 api 规范并加载两个 Swagger-UI 实例？处理此问题的最佳方法是什么？

例如。我有一个名为 /oauth/token 的端点，我想用一组 OAuth 授权代码流的参数来记录它，而相同的端点 /oauth/token 文档用于 client_credentials 流的不同参数集。

/oauth/token:
    post:
      summary: token endpoint for authorization_code flow
      parameters:
        - name: code
          type: string
          description: Required for Authorization Code Flow
          in: formData
          required: true
        - name: grant_type
          type: string
          description: Grant Type should be specified as authorization_code
          in: formData
          required: true
          default: authorization_code
          enum:
          - authorization_code
          - client_credentials
        - name: client_id
          type: string
          description: Consumer Key
          in: formData
          required: true
        - name: client_secret
          type: string
          description: Consumer Secret
          in: formData
          required: true
        - name: endOtherSessions
          in: formData
          type: boolean
          required: false
          default: false
          description: Optional parameter. Default is false - do not allow concurrent login. Send true to end any other user sessions.
      tags:
        - OAuth2 Authorization Code

client_credentials 流

的相同端点

/oauth/token2:
     post:
       summary: token for client credentials
       parameters:
         - name: grant_type
           type: string
           description: Grant Type should be specified as client_credentials
           in: formData
           required: true
           default: client_credentials
           enum:
          - authorization_code
          - client_credentials
         - name: client_id
           type: string
           description: Consumer Key
           in: formData
           required: true
         - name: client_secret
           type: string
           description: Consumer Secret
           in: formData
           required: true
       tags:
         - OAuth2 Client Credentials

Answer 1

由于问题是关于 OAuth2 而不是具有不同参数的单个端点，因此解决方案实际上是不同的。

Swagger 有一种特定的方式来记录授权方法，包括 4 个常见的 OAuth2 流程。

这些是使用 Security Definitions Object which is located at the top Swagger object 描述的。

在其中，您可以定义一个或多个 OAuth2 流程。规范本身为 implicit 流程提供了示例，但其他规范遵循类似的结构。不同之处在于提供的字段，即 authorizationUrl 和 tokenUrl（取决于流类型）。

完成后，您可以指定需要哪些安全方案。您可以为 Swagger object or at the Operation level.

处的所有操作指定它

规范允许您定义同时需要一组安全方法，或者用户可以在给定的集合之间进行选择。

Swagger 相同的路径指定了两次

Swagger same path specified twice

swagger

swagger-ui