RFC: Feature-enabled specification variants.

[ariesclark]

Some generators support certain syntax's that others don't, to provide the best support possible and closely model VRChat's API, relying on the most minimum support available across all generators leaves us with undesirable/broken SDKs.

I propose something similar to the following:

/auth/user:
    get:
      summary: Login and/or Get Current User Info
      tags:
        - authentication
      x-codeSamples:
        $ref: "../codeSamples/authentication.yaml#/~1auth~1user/get"
      responses:
        '200':
          x-feature:
            key: oneOf
            schema: 
              oneOf:
                - $ref: ../responses/authentication/CurrentUserLoginResponse.yaml
                - $ref: '#/components/schemas/TwoFactorRequired'
            fallback:
              $ref: ../responses/authentication/CurrentUserLoginResponse.yaml
        '401':
          $ref: ../responses/MissingCredentialsError.yaml

then during bundling/building, we're turn this into two specification files.

Resources

• https://redocly.com/docs/cli/decorators

Originally posted by @ariesclark in https://github.com/vrchatapi/vrchatapi-rust/issues/17#issuecomment-2246337894

Alternatives

• Drop support for generators that don't support it.

[ariesclark]

cc: @Foorack thoughts, concerns?

[0xkubectl]

Is there any other potential application for this besides responses?

[C0D3-M4513R]

Is there any other potential application for this besides responses?

This could be used to implement tag parsing too, by using one_of to either parse to an enum or a string as a fallback.

See the following commits:

• https://github.com/C0D3-M4513R/vrchatapi-rust/commit/838a126e3360148363a4989a0253397ca845195d
• https://github.com/C0D3-M4513R/vrchatapi-rust/commit/7fd98a0f59285a0a5cddac6740070c11f75525e4