Add support for general components and Reference Object [$ref]

[francesco-loreti]

According to OpenAPI 3 specifications, it is possible to declare general components that can be referenced using the
$ref: "#/components/[schemas, parameters]" command.
This is very useful when you have common parameters and data schemas that can simply be recalled as needed.

Is it possible to add this functionality, for example, in the configuration file?
Thanks for your job!!!

For example in YAML:

components:
  schemas:
    FiscalCode:
      type: string
      pattern: ^([A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST]{1}[0-9LMNPQRSTUV]{2}[A-Z]{1}[0-9LMNPQRSTUV]{3}[A-Z]{1})$|([0-9]{11})$
    Date:
      type: string
      format: date
      pattern: "^(\\d{4})-(\\d{2})-(\\d{2})$"
      example: "2025-01-01"
  parameters:
    fiscalcode:
      name: fiscalcode
      in: query
      description: Fiscal Code User
      schema:
        $ref: "#/components/schemas/FiscalCode"
    updated_from:
      name: updated_from
      in: query
      description: Update from
      schema:
        $ref: "#/components/schemas/Date"

OR

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: User ID.
        login:
          type: string
          description: Username.
/users:
  get:
    responses:
      '200':
        description: Elenco dipendenti
        content:
          application/json:
            schema:
              allOf:
              - $ref: "#/components/schemas/User"
              - type: object
                  properties:
                    field1:
                        type: string
                        description: Field1
                    field2:
                        type: string
                        description: Field2

[a-chacon]

hi @francesco-loreti ! You are welcome.

Yes, I am aware that the reusability is a problem in OasRails, repeating some request bodyes or params is hard. And what you propose can be a solution.

OasRails already uses this references, I create a hash with all structures and compare if this exists then I just add a reference, other way I create this object as component. Look at here for example:

oas_rails/lib/oas_rails/spec/components.rb

Line 25 in 4e2e4f8

def add_response(response)

Or just look an OAS generated by the engine, you will see that responses are just references to components.

I made it as it as a way to optimize the generation.

But what you say can give to the user the power to create this component and then in the tags just reference to it, just an idea, something like this:

# @response Success(200) ["#/components/responses/SuccessResponse"]

Here you have an endpoint generated by OasRails:

{

            "tags": [
                  "Projects"
            ],
            "summary": "Update project",
            "description": "",
            "operationId": "update_projects_id",
            "parameters": [
                  {
                        "$ref": "#/components/parameters/14338ed80ba33fefb5c2cfff70439c44"
                  }
            ],
            "requestBody": {
                  "$ref": "#/components/requestBodies/c4744a4e27286179b4334052f8544d6e"
            },
            "responses": {
                  "200": {
                        "$ref": "#/components/responses/83e8f45b01e2067edd8382566b5da929"
                  },
                  "401": {
                        "$ref": "#/components/responses/e96d6c0614b8a2bb00b5588ebb1d5af9"
                  },
                  "403": {
                        "$ref": "#/components/responses/12f10ee88400dd582b96154794cd256a"
                  },
                  "404": {
                        "$ref": "#/components/responses/46b1928a3a352098eb36fd0dc4641ba5"
                  },
                  "422": {
                        "$ref": "#/components/responses/34e13d972ee8d772a9f822aa6f6ba6a7"
                  },
                  "500": {
                        "$ref": "#/components/responses/73e249b56ec1a5c52803fd18ed513d1b"
                  }
            },
            "security": [
                  {
                        "bearer": [ ]
                  }
            ]

      },

So answering your question, this feature is absolutely possible to do, I think it should be a different file from config that should be merged into the OAS. But the problem is that currently I am focused to make OasRails framework-agnostic.

If you have time and want to contribute I will be very happy to help you with some guidelines to develop it and then review a PR, otherwise just open an Issue as a feature request describing it and I will take it in a future ;)

[francesco-loreti]

Hello @a-chacon, thank you for your work and suggestions!
I have created a fork of the project to explore possible approaches, though I need to delve deeper into what you have written to ensure my changes align with the logic you've used.
However, I came across the PR you're working on for agnostic, and I wonder whether it makes sense to modify the code now or wait for consolidation to guarantee proper object referencing, considering that you are moving away from Rails as a specific use case.
In the meantime, I'll save the few lines I've written, open an Issue as a reminder, and once you've completed your development and renamed the gem, I'll proceed with attempting a solution. :-)

[a-chacon]

hey! just save what you did. There is no need to wait my PR to be finished, made OasRails frameowkr agnostic is almost just change the logic of extract the routes, and this feature should not depend on that. Becouse of it I tell you that you can take it as an issue, then I just rebase my branch with the main changes.

I mean, adding this feature should not be in conflic with my other work. But if you prefer to wait it is not a problem. I will check the issue and write some guidelines to develop it. Let's continue the discuss there!

#131