Documenting multiple POST request for OAUTH under same resource RAML

I realize that the title might be a little bit confusing so here is what I am trying to achieve:

I need to document token_grant and token_refresh methods using RAML both of which are POST calls.

token_grant: generate the first time OAuth token token_refresh: refresh the access token

They differ in query parameters and of course different return results. The problem is they are both under the same resource and RAML allows only 1 POST call for each resource:

 /oauth/token

Is there a way I can work around this, being limited to one post call? Maybe having something conditional to be depending on the query parameters?

Here is the template for token_grant

/oauth/token:  
   post:
     description:
     headers:
       Authorization:
         type: "string"
         default: "[client_id:]"
         required: true
         example: 
     queryParameters:
       grant_type:
         type: string
         required: true
         example: ''
       code:
         type: string
         required: true
         example: ''
     responses:
       200:
         body:
         application/json:
       example: |

And here is the template for token_refresh:

/oauth/token:  
   post:
     description:
     headers:
       Authorization:
         type: "string"
         default: "[client_id:]"
         required: true
         example: 
     queryParameters:
       grant_type:
         type: string
         required: true
         example: ''
       //Main difference1
       refresh_token:
         type: string
         required: true
         example: ''
     responses:
       200:
         body:
          application/json:
          //Main difference 2
          example: "a different response goes here"

So the main question would be how to put these together under

/oauth/token/

Any help is appreciated Thanks a lot!

Solution

You do not need to specify the OAuth2 protocol in RAML, as this security scheme is supported by default: https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#security

All you need to define are URIs, grants and scopes: https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#oauth-20 and the header in which you expect the access token: https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#declaration-1

Any OAuth2 aware client will have then enough information to use your API because the OAuth2 spec itself describes the code/token resource interactions.