CODEWITHSUNDEEP
swaggerswagger-ui
Vineet Bhatia
Vineet Bhatia

Reputation: 2533

Swagger same path specified twice

Is it possible to have same path appear more than once in one API spec which is being rendered by Swagger-UI?

Should I create separate api specs and load two instances of Swagger-UI? What is the best way to handle this?

For ex. I have endpoint called /oauth/token which I want to document with one set of parameters for OAuth Authorization Code flow and the same endpoint /oauth/token documents for client_credentials flow with different set of parameters.

/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

Same endpoint for client_credentials flow 

/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

Upvotes: 0

Views: 3002

Answers (1)

Ron
Ron

Reputation: 14800

Since the question is about OAuth2 rather than a single endpoint with different parameters, then the solution is actually different.

Swagger has a specific way to document authorization methods, including the 4 common OAuth2 flows.

These are described using the Security Definitions Object which is located at the top Swagger object.

Within it, you can define one or more OAuth2 flows. The spec itself provides a sample for the implicit flow, but others follow a similar structure. The difference is by which fields are provided, namely authorizationUrl and tokenUrl (depending on the flow type).

Once you have that, you can specify which security schemes are required. You can specify it for all the operations at the Swagger object or at the Operation level.

The spec allows you to define that a set of security methods are required together, or that the user can choose between given sets.

Upvotes: 2

Related Questions