Usung traits in securitySchemes


#1

Is there any possibility to use traits in securitySchemes?

Use Case:
I do have traits set up für our responses with 401, 403 etc. So they are standardized over all APIs and responses.
If I now set up a securityScheme, i.e. for OAuth 2, and want to include the responses für 401 and 403, I want to reuse my traits here. I don’t want to copy-paste the content of the trait in the scheme and manage redundant code in different files.

Does anyone have a solution for that?

Thanks!


#2

@Joo: I am not sure to understand what you’re trying to achieve. Would you mind sharing a RAML example that illustrates your question?


#3

Simple example for using traits in security schemes:
Look at the Dropbox example:

securitySchemes:
oauth_2_0:
  description: |
      Dropbox supports OAuth 2.0 for authenticating all API requests.
  type: OAuth 2.0
  describedBy:
      headers:
          Authorization:
              description: |
                 Used to send a valid OAuth 2 access token. Do not use
                 with the "access_token" query string parameter.
              type: string
      queryParameters:
          access_token:
              description: |
                 Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header
              type: string
      responses:
          401:
              description: |
                  Bad or expired token. This can happen if the user or Dropbox
                  revoked or expired an access token. To fix, you should re-
                  authenticate the user.
          403:
              description: |
                  Bad OAuth request (wrong consumer key, bad nonce, expired
                  timestamp...). Unfortunately, re-authenticating the user won't help here.

There are responses for 401 and 403.

Now, all our APIs do have the same trait for i.e. 403 responses. Example:

#%RAML 1.0 Trait
usage: |
  Use this trait for every 403er response.
uses:
  SharedTypes: ../types/common/SharedTypes.raml
responses:
  403:
    description: |
      Forbidden.
      Some description.
      Possible error messages are:
      <<errorMessages403>>
    body:
      application/json:
        type: SharedTypes.Error-v2
        example: !include ../examples/error/common-error-403-v2.json
    headers:
      X-Some-Header:
        description: |
          HTTP Custom Parameter.
          Some description.
        type: datetime
        required: false
        example: 2017-12-31T23:59:59.0+01:00

How can I use this trait in the security scheme?