[OpenAPI] Shared Components in the `@auth` tag

[rsamoilov]

Description

Currently, Rage supports specifying security schemes for an application using the @auth tag.

The tag supports two forms:

• using the default scheme:

# @auth authenticate_user

• using a custom scheme inlined into the tag:

# @auth authenticate_by_token
#   type: apiKey
#   in: header
#   name: X-API-Key

Unless it is something really simple and straightforward, we recommend avoiding inlining YAML into tags. Thus, it makes sense to update the @auth tag to accept a shared reference. For example:

# @auth authenticate_by_token #/components/securitySchemes/ApiKeyAuth

Such tag would apply the ApiKeyAuth security scheme to all necessary controller actions.

Tips

• Check OpenAPI Authentication Guide.
• The starting point for the code that generates OpenAPI documentation is Rage::OpenAPI::Builder. The changes, however, will need to be made in Rage::OpenAPI::Parser and Rage::OpenAPI::Converter.
• Check the architecture doc that shows how Rage's core components interact with each other.
• Feel free to ask any questions or request help in the comments below!