两次指定Swager相同路径

Question

在一个由Swagger-UI渲染的API规范中，同一个路径是否可能出现不止一次？

我应该创建单独的api规范并加载两个Swagger-UI实例吗？处理这件事的最好方法是什么？

例如，我有一个名为/oauth/token的endpoint，我想用一组oauth Authorization Code流的参数对其进行记录，用一组不同的参数对client_credentials流的同一个endpoint/oauth-token文档进行记录。

/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流的相同endpoint

/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而不是参数不同的单个endpoint，那么解决方案实际上是不同的。

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

这些使用位于顶部Swagger对象的安全定义对象来描述。

在其中，您可以定义一个或多个OAuth2流。该规范本身为< code>implicit流提供了一个示例，但其他规范遵循类似的结构。区别在于提供了哪些字段，即< code>authorizationUrl和< code>tokenUrl(取决于流类型)。

一旦您有了它，您就可以指定需要哪些安全方案。您可以为Swagger对象或操作级别的所有操作指定它。

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