Support for RAR

[jricher]

Support for the OAuth 2.0 Rich Authorization Requests draft specification would require the specification of the type field values required for the access token to be accepted. For each type value, there's also the usually the need to define other values or parameters within the object. The following examples show what a possible syntax could look like for the new OAS security model proposed in OAI/OpenAPI-Specification#2582.

This example shows how it could be defined for an example API using OAuth 2 bearer tokens

components:
  securitySchemes:
    photoApi:
      type: oauth2-rar
      credentials:
      - in: header
        name: authorization
        format: ^[B|b][E|e][A|a][R|r][E|e][R|r] (.*)$
      config:
        types:
        - type: photo-api
          actions:
          - read
          - write
          - dolphin
          locations:
          - <api endpoint url>
          datatypes:
          - image
          - metadata
        - type: bank-api
          actions:
          - read
          locations:
          - <api endpoint url>
          identifier: <account id>
          datatypes:
          - account

As I'm not sure how to show placeholder values, I'm using things like <api endpoint url> here.

Furthermore, each type value could define its own schema for what's allowed and required under its config space, to make this more automated. In general, the values under the types array could be any object structure, with only the type field required. Perhaps the overlays function can help with this?

This proposed syntax is just one possible idea, and I'm looking for feedback on how this could be made to fit the OAS model better.

Addresses #6