feat: introduce oas extensions for oauth (client credentials)

[armandobelardo]

Fixes FER-2444

The schema effectively takes the schema for the Fern Definition, except endpoints are specified as METHOD URL.

The idea is you can explicitly specify the schema in extensions only:

x-fern-oauth:
  - flow: clientCredentials
    clientId:
      name: username
      env: MY_CLIENT_ID
    clientSecret:
      name: password
      env: MY_CLIENT_ID
    tokenPrefix: Bearer
    getToken:
      endpoint: GET https://example.com/token
      request:
        clientId: $query.client_id
        clientSecret: $query.client_secret
        scopes: $query.scopes
      response:
        accessToken: $response.access_token
        expiresIn: $response.access_token
        refreshToken: $response.refresh_token
    refreshToken:
      endpoint: GET https://example.com/refresh
      request:
        refreshToken: $query.refresh_token
      response:
        accessToken: $response.access_token
        expiresIn: $response.access_token
        refreshToken: $response.refresh_token
    scopes: ["scope1", "scope2"]

The idea here is to have a very Fern way to be able to back door the definition without having to cover every edge case in OAS. For example, if there are multiple endpoints of different methods but the same path, there does not seem to be a way to specify that in OAS today (ex: authorizationUrl: https://api.example.com/oauth2/authorize).

Alternaively, trying to meet users where they are, they can just add the info we need to the scheme through these targetted extensions Enrich the access + refresh token endpoints:

components:
  securitySchemes:
    oAuthSample:
      type: oauth2
      flows:
        clientCredentials:
        authorizationUrl: https://api.example.com/oauth2/authorize
        x-fern-access-token-endpoint:
          request:
            clientId: $query.client_id
            clientSecret: $query.client_secret
            scopes: $query.scopes
          response:
            accessToken: $response.access_token
            expiresIn: $response.access_token
            refreshToken: $response.refresh_token
        refreshUrl: https://api.example.com/oauth2/refresh
        x-fern-refresh-token-endpoint:
          request:
            clientId: $query.client_id
            clientSecret: $query.client_secret
            scopes: $query.scopes
          response:
            accessToken: $response.access_token
            expiresIn: $response.access_token
            refreshToken: $response.refresh_token