oas_core 0.5.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8396df67f2123727d598bd1860f44b8595776b8564ad39b8c788bcfad839a522
-  data.tar.gz: 4e6525b5259d2b105edfaa094e04e4ee778453d5500208f692849c165a340596
+  metadata.gz: fc7875de7f736a4c22a97996c6fd5073eb1f7486380da2822079d5698533f838
+  data.tar.gz: 03c6a672ec713bbdfd205f8aab8c50f30fa8bb5e935225a254bab98096cdd810
 SHA512:
-  metadata.gz: fab7a5e69cc18c3745d9780ccfee5e9ab0ada24515efde300c7dbdce04f19f68331d394506da5fb71f1b6299ed74f6ce19913c513440c0ab5c1909cd45f20f8b
-  data.tar.gz: 2e7ccf626a4c5aaeba13f9930d0853605bca4060c69977a50488df36c92dbd79059751c1fc63682cbeadbc7fc819f3537ab3442462b385dc4ecbfdc70657be08
+  metadata.gz: 2d6bf9b134a6b23d98fd49a7e731dc3d5034dfa3208de61805ca91d1a33ee126acef7e963d2865a6ca7c4becf80d2f17d6b5fc063dcf78fc53545862ceb083c7
+  data.tar.gz: cee566dc9b35190ddef8109e836dd4473de56ee27f5c936b3f818157d1edd86d2a9d854e3f2a0a202d39b44d464ce007bf5345a9dc84c6e16197ff8628102d1a

data/README.md

@@ -10,7 +10,11 @@ OasCore is a Ruby gem designed to generate Open API Specification (OAS) 3.1 docu
 
 ## Framework adapters
 
-- **[OasRails](https://github.com/a-chacon/oas_rails)**
+- **[OasRails](https://github.com/a-chacon/oas_rails)**: For Ruby on Rails framework.
+
+- **[OasHanami](https://github.com/a-chacon/oas_hanami)**: For [Hanami](https://github.com/hanami/hanami) framework.
+
+- **[OasRage](https://github.com/a-chacon/oas_rage)**: For [Rage](https://github.com/rage-rb/rage) framework.
 
 ## Documentation
 

data/lib/oas_core/builders/content_builder.rb

@@ -3,15 +3,18 @@
 module OasCore
   module Builders
     class ContentBuilder
-      def initialize(specification, context)
-        @context = context || :incoming
+      def initialize(specification)
         @specification = specification
         @media_type = Spec::MediaType.new(specification)
         @content_type = 'application/json'
       end
 
       def with_schema(schema)
-        @media_type.schema = @specification.components.add_schema(schema)
+        @media_type.schema = if schema.is_a? OasCore::Spec::Reference
+                               schema
+                             else
+                               @specification.components.add_schema(schema)
+                             end
 
         self
       end
@@ -31,11 +34,15 @@ module OasCore
       def with_examples_from_tags(tags)
         @media_type.examples = @media_type.examples.merge(tags.each_with_object({}).with_index(1) do |(example, result), _index|
           key = example.text.downcase.gsub(' ', '_')
-          value = {
-            'summary' => example.text,
-            'value' => example.content
-          }
-          result[key] = @specification.components.add_example(value)
+          if example.content.is_a? OasCore::Spec::Reference
+            result[key] = example.content
+          else
+            value = {
+              'summary' => example.text,
+              'value' => example.content
+            }
+            result[key] = @specification.components.add_example(value)
+          end
         end)
 
         self

data/lib/oas_core/builders/operation_builder.rb

@@ -15,7 +15,7 @@ module OasCore
         @operation.tags = extract_tags(oas_route:)
         @operation.security = extract_security(oas_route:)
         @operation.parameters = ParametersBuilder.new(@specification).from_oas_route(oas_route).build
-        @operation.request_body = RequestBodyBuilder.new(@specification).from_oas_route(oas_route).reference
+        @operation.request_body = extract_request_body(oas_route)
         @operation.responses = ResponsesBuilder.new(@specification)
                                                .from_oas_route(oas_route)
                                                .add_default_responses(oas_route, !@operation.security.empty?).build
@@ -82,6 +82,14 @@ module OasCore
           destroy: 'Delete'
         }.fetch(method.to_sym)
       end
+
+      def extract_request_body(oas_route)
+        if (ref_tag = oas_route.tags(:request_body_ref).first)
+          ref_tag.reference
+        else
+          RequestBodyBuilder.new(@specification).from_oas_route(oas_route).reference
+        end
+      end
     end
   end
 end

data/lib/oas_core/builders/parameters_builder.rb

@@ -15,6 +15,10 @@ module OasCore
           @parameters << ParameterBuilder.new(@specification).from_path(oas_route.path, p).build unless @parameters.any? { |param| param.name.to_s == p.to_s }
         end
 
+        oas_route.tags(:parameter_ref)&.each do |ref_tag|
+          @parameters << ref_tag.reference
+        end
+
         self
       end
 
@@ -34,7 +38,11 @@ module OasCore
 
       def build
         @parameters.map do |p|
-          @specification.components.add_parameter(p)
+          if p.is_a? OasCore::Spec::Reference
+            p
+          else
+            @specification.components.add_parameter(p)
+          end
         end
       end
     end

data/lib/oas_core/builders/request_body_builder.rb

@@ -19,7 +19,7 @@ module OasCore
 
       def from_tags(tag:, examples_tags: [])
         @request_body.description = tag.text
-        @request_body.content = ContentBuilder.new(@specification, :incoming).with_schema(tag.schema).with_examples_from_tags(examples_tags).with_content_type(tag.content_type).build
+        @request_body.content = ContentBuilder.new(@specification).with_schema(tag.content).with_examples_from_tags(examples_tags).with_content_type(tag.content_type).build
         @request_body.required = tag.required
 
         self

data/lib/oas_core/builders/response_builder.rb

@@ -27,9 +27,9 @@ module OasCore
       end
 
       def from_tag(tag)
-        @response.code = tag.name.to_i
+        @response.code = tag.code.to_i
         @response.description = tag.text
-        @response.content = ContentBuilder.new(@specification, :outgoing).with_schema(tag.schema).build
+        @response.content = ContentBuilder.new(@specification).with_schema(tag.content).build
 
         self
       end

data/lib/oas_core/builders/responses_builder.rb

@@ -15,15 +15,18 @@ module OasCore
 
       def from_oas_route(oas_route)
         oas_route.tags(:response).each do |tag|
-          content = @content_builder.new(@specification,
-                                         :outgoing).with_schema(tag.schema).with_examples_from_tags(oas_route.tags(:response_example).filter do |re|
-                                                                                                      re.code == tag.name
-                                                                                                    end).build
-          response = @response_builder.new(@specification).with_code(tag.name.to_i).with_description(tag.text).with_content(content).build
+          content = @content_builder.new(@specification).with_schema(tag.content).with_examples_from_tags(oas_route.tags(:response_example).filter do |re|
+            re.code == tag.code
+          end).build
+          response = @response_builder.new(@specification).with_code(tag.code.to_i).with_description(tag.text).with_content(content).build
 
           @responses.add_response(response)
         end
 
+        oas_route.tags(:response_ref)&.each do |ref_tag|
+          @responses.add_reference_response(ref_tag.code, ref_tag.reference)
+        end
+
         self
       end
 
@@ -63,8 +66,7 @@ module OasCore
       def add_responses_for_errors(errors)
         errors.each do |error|
           response_body = resolve_response_body(error)
-          content = @content_builder.new(@specification,
-                                         :outgoing).with_schema(@json_schema_generator.process_string(response_body)[:json_schema]).build
+          content = @content_builder.new(@specification).with_schema(@json_schema_generator.process_string(response_body)[:json_schema]).build
           code = @utils.status_to_integer(error)
           response = @response_builder.new(@specification).with_code(code).with_description(@utils.get_definition(code)).with_content(content).build
 

data/lib/oas_core/configuration.rb

@@ -9,8 +9,7 @@ module OasCore
                   :authenticate_all_routes_by_default,
                   :set_default_responses,
                   :possible_default_responses,
-                  :http_verbs,
-                  :use_model_names
+                  :http_verbs
 
     attr_reader :servers, :tags, :security_schema, :response_body_of_default
 
@@ -29,8 +28,6 @@ module OasCore
                                        unprocessable_entity]
       @http_verbs = %i[get post put patch delete]
       @response_body_of_default = 'Hash{ status: !Integer, error: String }'
-      # TODO: What does this config??
-      @use_model_names = false
 
       @possible_default_responses.each do |response|
         method_name = "response_body_of_#{response}="

data/lib/oas_core/json_schema_generator.rb

@@ -52,6 +52,7 @@ module OasCore
       end
     end
 
+    # rubocop:disable Metrics
     # Parses the properties of an object type from a string.
     #
     # @param str [String] The string representation of the object's properties.
@@ -97,6 +98,7 @@ module OasCore
 
       properties
     end
+    # rubocop:enable Metrics
 
     # Converts a parsed data type into a JSON schema format.
     #
@@ -128,11 +130,11 @@ module OasCore
       end
     end
 
+    # rubocop:disable Metrics
     # Converts a Ruby data type into its corresponding JSON schema type.
     #
     # @param type [Symbol, String] The Ruby data type.
     # @return [Hash, String] The JSON schema type or a hash with additional format information.
-    # rubocop:disable Metrics/CyclomaticComplexity
     def self.ruby_type_to_json_schema_type(type)
       case type.to_s.downcase
       when 'string' then { type: 'string' }
@@ -148,6 +150,6 @@ module OasCore
       else type.to_s.downcase
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics
   end
 end

data/lib/oas_core/spec/components.rb

@@ -21,8 +21,18 @@ module OasCore
         @callbacks = {}
       end
 
-      def oas_fields
-        %i[request_bodies examples responses schemas parameters security_schemes]
+      def to_spec
+        {
+          schemas: @schemas,
+          responses: @responses.transform_values(&:to_spec),
+          parameters: @parameters.transform_values(&:to_spec),
+          requestBodies: @request_bodies.transform_values(&:to_spec),
+          securitySchemes: @security_schemes,
+          headers: @headers.transform_values(&:to_spec),
+          examples: @examples,
+          links: @links.transform_values(&:to_spec),
+          callbacks: @callbacks.transform_values(&:to_spec)
+        }.compact
       end
 
       def add_response(response)
@@ -47,20 +57,9 @@ module OasCore
       end
 
       def add_schema(schema)
-        key = nil
-        if OasCore.config.use_model_names
-          if schema[:type] == 'array'
-            arr_schema = schema[:items]
-            arr_key = arr_schema['title']
-            key = "#{arr_key}List" unless arr_key.nil?
-          else
-            key = schema['title']
-          end
-        end
-
-        key = Hashable.generate_hash(schema) if key.nil?
-
+        key = Hashable.generate_hash(schema)
         @schemas[key] = schema if @schemas[key].nil?
+
         schema_reference(key)
       end
 

data/lib/oas_core/spec/media_type.rb

@@ -10,7 +10,6 @@ module OasCore
       # Initializes a new MediaType object.
       #
       # @param schema [Hash] the schema of the media type.
-      # @param kwargs [Hash] additional keyword arguments.
       def initialize(specification)
         @specification = specification
         @schema = {}

data/lib/oas_core/spec/response.rb

@@ -12,6 +12,7 @@ module OasCore
         @specification = specification
         @description = ''
         @content = {} # Hash with {content: MediaType}
+        @code = 200
       end
 
       def oas_fields

data/lib/oas_core/spec/responses.rb

@@ -15,12 +15,12 @@ module OasCore
         @responses[response.code] = @specification.components.add_response(response)
       end
 
+      def add_reference_response(code, reference)
+        @responses[code] = reference
+      end
+
       def to_spec
-        spec = {}
-        @responses.each do |key, value|
-          spec[key] = value.to_spec
-        end
-        spec
+        @responses.transform_values(&:to_spec)
       end
     end
   end

data/lib/oas_core/spec/specable.rb

@@ -8,30 +8,12 @@ module OasCore
       end
 
       def to_spec
-        hash = {}
-        oas_fields.each do |var|
-          key = var.to_s
-
-          camel_case_key = key.camelize(:lower).to_sym
+        oas_fields.each_with_object({}) do |var, hash|
+          key = var.to_s.camelize(:lower).to_sym
           value = send(var)
-
-          processed_value = if value.respond_to?(:to_spec)
-                              value.to_spec
-                            elsif value.is_a?(Array) && value.all? { |elem| elem.respond_to?(:to_spec) }
-                              value.map(&:to_spec)
-                            # elsif value.is_a?(Hash)
-                            #   hash = {}
-                            #   value.each do |key, object|
-                            #     hash[key] = object.to_spec
-                            #   end
-                            #   hash
-                            else
-                              value
-                            end
-
-          hash[camel_case_key] = processed_value unless valid_processed_value?(processed_value)
+          processed_value = process_value(value)
+          hash[key] = processed_value unless valid_processed_value?(processed_value)
         end
-        hash
       end
 
       # rubocop:disable Lint/UnusedMethodArgument
@@ -42,6 +24,26 @@ module OasCore
 
       private
 
+      def process_value(value)
+        if value.respond_to?(:to_spec)
+          value.to_spec
+        elsif value.is_a?(Array)
+          process_array(value)
+        elsif value.is_a?(Hash)
+          process_hash(value)
+        else
+          value
+        end
+      end
+
+      def process_array(array)
+        array.all? { |elem| elem.respond_to?(:to_spec) } ? array.map(&:to_spec) : array
+      end
+
+      def process_hash(hash)
+        hash.transform_values { |val| val.respond_to?(:to_spec) ? val.to_spec : val }
+      end
+
       def valid_processed_value?(processed_value)
         ((processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?) || processed_value.nil?
       end

data/lib/oas_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OasCore
-  VERSION = '0.5.3'
+  VERSION = '1.0.0'
 end

data/lib/oas_core/yard/oas_core_factory.rb

@@ -2,14 +2,22 @@
 
 module OasCore
   module YARD
+    class TagParsingError < StandardError; end
+
     class OasCoreFactory < ::YARD::Tags::DefaultFactory
       # Parses a tag that represents a request body.
       # @param tag_name [String] The name of the tag.
       # @param text [String] The tag text to parse.
       # @return [RequestBodyTag] The parsed request body tag object.
       def parse_tag_with_request_body(tag_name, text)
-        description, klass, schema, required, content_type = extract_description_and_schema(text.squish)
-        RequestBodyTag.new(tag_name, description, klass, schema:, required:, content_type:)
+        description, raw_type = split_description_and_type(text.squish)
+        description, content_type = text_and_last_parenthesis_content(description)
+        raw_type, required = text_and_required(raw_type)
+        content = raw_type_to_content(raw_type)
+
+        RequestBodyTag.new(tag_name, description, content:, required:, content_type:)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse request body tag: #{e.message}"
       end
 
       # Parses a tag that represents a request body example.
@@ -17,9 +25,13 @@ module OasCore
       # @param text [String] The tag text to parse.
       # @return [RequestBodyExampleTag] The parsed request body example tag object.
       def parse_tag_with_request_body_example(tag_name, text)
-        description, _, hash = extract_description_type_and_content(text.squish, process_content: true,
-                                                                                 expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
-        RequestBodyExampleTag.new(tag_name, description, content: hash)
+        description, raw_type = split_description_and_type(text.squish)
+        raw_type, = text_and_required(raw_type)
+        content = raw_type_to_content(raw_type)
+
+        RequestBodyExampleTag.new(tag_name, description, content: content)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse request body example tag: #{e.message}"
       end
 
       # Parses a tag that represents a parameter.
@@ -27,9 +39,20 @@ module OasCore
       # @param text [String] The tag text to parse.
       # @return [ParameterTag] The parsed parameter tag object.
       def parse_tag_with_parameter(tag_name, text)
-        name, location, schema, required, description = extract_name_location_schema_and_description(text.squish)
+        match = text.squish.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        if match
+          first = match[1]
+          second = match[2]
+          description = match[3]
+        end
+        name, location = text_and_last_parenthesis_content(first)
+        raw_type, required = text_and_required(second)
+        schema = raw_type_to_content(raw_type)
         name = "#{name}[]" if location == 'query' && schema[:type] == 'array'
-        ParameterTag.new(tag_name, name, description, schema, location, required:)
+
+        ParameterTag.new(tag_name, name, description.strip, schema, location, required:)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse parameter tag: #{e.message}"
       end
 
       # Parses a tag that represents a response.
@@ -37,8 +60,13 @@ module OasCore
       # @param text [String] The tag text to parse.
       # @return [ResponseTag] The parsed response tag object.
       def parse_tag_with_response(tag_name, text)
-        name, code, schema = extract_name_code_and_schema(text.squish)
-        ResponseTag.new(tag_name, code, name, schema)
+        description, raw_type = split_description_and_type(text.squish)
+        description, code = text_and_last_parenthesis_content(description)
+        content = raw_type_to_content(raw_type)
+
+        ResponseTag.new(tag_name, description, code, content)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse response tag: #{e.message}"
       end
 
       # Parses a tag that represents a response example.
@@ -46,79 +74,67 @@ module OasCore
       # @param text [String] The tag text to parse.
       # @return [ResponseExampleTag] The parsed response example tag object.
       def parse_tag_with_response_example(tag_name, text)
-        description, code, hash = extract_name_code_and_hash(text.squish)
-        ResponseExampleTag.new(tag_name, description, content: hash, code:)
-      end
-
-      private
+        description, raw_type = split_description_and_type(text.squish)
+        description, code = text_and_last_parenthesis_content(description)
+        content = raw_type_to_content(raw_type)
 
-      # Reusable method for extracting description, type, and content with an option to process content.
-      # @param text [String] The text to parse.
-      # @param process_content [Boolean] Whether to evaluate the content as a hash.
-      # @return [Array] An array containing the description, type, and content or remaining text.
-      def extract_description_type_and_content(text, process_content: false, expresion: /^(.*?)\s*\[(.*)\]\s*(.*)$/)
-        match = text.match(expresion)
-        raise ArgumentError, "Invalid tag format: #{text}" if match.nil?
-
-        description = match[1].strip
-        type = match[2].strip
-        content = process_content ? eval_content(match[3].strip) : match[3].strip
-
-        [description, type, content]
+        ResponseExampleTag.new(tag_name, description, content: content, code:)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse response example tag: #{e.message}"
       end
 
-      # Specific method to extract description and schema for request body tags.
-      # @param text [String] The text to parse.
-      # @return [Array] An array containing the description, class, schema, required flag and content type.
-      def extract_description_and_schema(text)
-        description, type, = extract_description_type_and_content(text)
-        description, content_type = extract_text_and_parentheses_content(description)
-
-        klass, schema, required = type_text_to_schema(type)
-        [description, klass, schema, required, content_type]
+      # Parses a tag that represents a parameter reference.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ParameterReferenceTag] The parsed parameter reference tag object.
+      def parse_tag_with_parameter_reference(tag_name, text)
+        ref = text.strip
+        reference = OasCore::Spec::Reference.new(ref)
+        ParameterReferenceTag.new(tag_name, reference)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse parameter reference tag: #{e.message}"
       end
 
-      # Specific method to extract name, location, and schema for parameters.
-      # @param text [String] The text to parse.
-      # @return [Array] An array containing the name, location, schema, and required flag.
-      def extract_name_location_schema_and_description(text)
-        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
-        name, location = extract_text_and_parentheses_content(match[1].strip)
-        schema, required = type_text_to_schema(match[2].strip)[1..]
-        description = match[3].strip
-        [name, location, schema, required, description]
+      # Parses a tag that represents a request body reference.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [RequestBodyReferenceTag] The parsed request body reference tag object.
+      def parse_tag_with_request_body_reference(tag_name, text)
+        ref = text.strip
+        reference = OasCore::Spec::Reference.new(ref)
+        RequestBodyReferenceTag.new(tag_name, reference)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse request body reference tag: #{e.message}"
       end
 
-      # Specific method to extract name, code, and schema for responses.
-      # @param text [String] The text to parse.
-      # @return [Array] An array containing the name, code, and schema.
-      def extract_name_code_and_schema(text)
-        name, code = extract_text_and_parentheses_content(text)
-        _, type, = extract_description_type_and_content(text)
-        schema = type_text_to_schema(type)[1]
-        [name, code, schema]
+      # Parses a tag that represents a response reference.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ResponseReferenceTag] The parsed response reference tag object.
+      def parse_tag_with_response_reference(tag_name, text)
+        reference_str, code_text = text_and_first_parenthesis_content(text.strip)
+        reference = OasCore::Spec::Reference.new(reference_str)
+        ResponseReferenceTag.new(tag_name, reference, code: code_text.to_i)
+      rescue StandardError => e
+        raise TagParsingError, "Failed to parse response reference tag: #{e.message}"
       end
 
-      # Specific method to extract name, code, and hash for responses examples.
-      # @param text [String] The text to parse.
-      # @return [Array] An array containing the name, code, and schema.
-      def extract_name_code_and_hash(text)
-        name, code = extract_text_and_parentheses_content(text)
-        _, _, content = extract_description_type_and_content(text, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
-        hash = eval_content(content)
-        [name, code, hash]
-      end
+      private
 
-      # Evaluates a string as a hash, handling errors gracefully.
-      # @param content [String] The content string to evaluate.
-      # @return [Hash] The evaluated hash, or an empty hash if an error occurs.
-      # rubocop:disable Security/Eval
-      def eval_content(content)
-        eval(content)
-      rescue StandardError
-        {}
+      # Converts raw_type to content based on its format.
+      # @param raw_type [String] The raw type string to process.
+      # @return [Hash] The processed content.
+      def raw_type_to_content(raw_type)
+        if raw_type.start_with?('JSON')
+          json_string = raw_type.sub(/^JSON/, '').gsub(/'/, '"')
+          JSON.parse(json_string)
+        elsif raw_type.start_with?('Reference:')
+          ref = raw_type.sub(/^Reference:/, '').strip
+          OasCore::Spec::Reference.new(ref)
+        else
+          JsonSchemaGenerator.process_string(raw_type)[:json_schema]
+        end
       end
-      # rubocop:enable Security/Eval
 
       # Parses the position name and location from input text.
       # @param input [String] The input text to parse.
@@ -142,26 +158,48 @@ module OasCore
         end
       end
 
-      # Matches and validates a description and type from text.
+      # Splits the text into description with detail and type parts.
       # @param text [String] The text to parse.
-      # @return [MatchData] The match data from the regex.
-      def description_and_type(text)
-        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
-        raise ArgumentError, "The request body tag is not valid: #{text}" if match.nil?
+      # @return [Array] An array containing the description with detail and the type.
+      def split_description_and_type(text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]$/)
+        raise TagParsingError, "Invalid format: #{text}" if match.nil?
 
-        match
+        [match[1].strip, match[2].strip]
       end
 
-      # Converts type text to a schema, checking if it's an ActiveRecord class.
-      # @param text [String] The type text to convert.
-      # @return [Array] An array containing the class, schema, and required flag.
-      def type_text_to_schema(text)
-        type_text, required = text_and_required(text)
-
-        schema = JsonSchemaGenerator.process_string(type_text)[:json_schema]
-        klass = Object
+      # Extracts the description and the detail (content of the last parentheses) from the text.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the description and the detail.
+      def text_and_last_parenthesis_content(text)
+        # Find the last occurrence of parentheses
+        last_open = text.rindex('(')
+        last_close = text.rindex(')')
+
+        if last_open && last_close && last_open < last_close
+          description = text[0...last_open].strip
+          detail = text[(last_open + 1)...last_close].strip
+          [description, detail]
+        else
+          [text.strip, nil]
+        end
+      end
 
-        [klass, schema, required]
+      # Extracts the first occurrence of content inside parentheses and the rest of the text.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the rest of the text and the first detail in parentheses.
+      def text_and_first_parenthesis_content(text)
+        # Find the first occurrence of parentheses
+        first_open = text.index('(')
+        first_close = text.index(')')
+
+        if first_open && first_close && first_open < first_close
+          detail = text[(first_open + 1)...first_close].strip
+          rest = (text[0...first_open] + text[(first_close + 1)..]).strip
+          [rest, detail]
+        else
+          [text.strip, nil]
+        end
       end
     end
   end

data/lib/oas_core/yard/parameter_reference_tag.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ParameterReferenceTag < ReferenceTag
+    end
+  end
+end

data/lib/oas_core/yard/parameter_tag.rb

@@ -5,11 +5,11 @@ module OasCore
     class ParameterTag < ::YARD::Tags::Tag
       attr_accessor :schema, :required, :location
 
-      def initialize(tag_name, name, text, schema, location, required: false)
+      def initialize(tag_name, name, text, *args, **kwargs)
         super(tag_name, text, nil, name)
-        @schema = schema
-        @required = required
-        @location = location
+        @schema = args[0] || kwargs.fetch(:schema, nil)
+        @location = args[1] || kwargs.fetch(:location, nil)
+        @required = kwargs.fetch(:required, false)
       end
     end
   end

data/lib/oas_core/yard/reference_tag.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ReferenceTag < ::YARD::Tags::Tag
+      attr_accessor :reference
+
+      def initialize(tag_name, reference)
+        super(tag_name, nil, nil, nil)
+        @reference = reference
+      end
+    end
+  end
+end

data/lib/oas_core/yard/request_body_example_tag.rb

@@ -3,11 +3,6 @@
 module OasCore
   module YARD
     class RequestBodyExampleTag < ExampleTag
-      attr_accessor :content
-
-      def initialize(tag_name, text, content: {})
-        super
-      end
     end
   end
 end

data/lib/oas_core/yard/request_body_reference_tag.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class RequestBodyReferenceTag < ReferenceTag
+    end
+  end
+end

data/lib/oas_core/yard/request_body_tag.rb

@@ -3,13 +3,12 @@
 module OasCore
   module YARD
     class RequestBodyTag < ::YARD::Tags::Tag
-      attr_accessor :klass, :schema, :required, :content_type
+      attr_accessor :content, :required, :content_type
 
-      def initialize(tag_name, text, klass, schema: {}, required: false, content_type: 'application/json')
+      def initialize(tag_name, text, content: nil, required: false, content_type: 'application/json')
         # initialize(tag_name, text, types = nil, name = nil)
         super(tag_name, text, nil, nil)
-        @klass = klass
-        @schema = schema
+        @content = content
         @required = required
         @content_type = content_type
       end

data/lib/oas_core/yard/response_example_tag.rb

@@ -5,7 +5,7 @@ module OasCore
     class ResponseExampleTag < ExampleTag
       attr_accessor :code
 
-      def initialize(tag_name, text, content: {}, code: 200)
+      def initialize(tag_name, text, content: nil, code: 200)
         super(tag_name, text, content:)
         @code = code
       end

data/lib/oas_core/yard/response_reference_tag.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ResponseReferenceTag < ReferenceTag
+      attr_accessor :code
+
+      def initialize(tag_name, reference, code: 200)
+        super(tag_name, reference)
+        @code = code
+      end
+    end
+  end
+end

data/lib/oas_core/yard/response_tag.rb

@@ -3,12 +3,13 @@
 module OasCore
   module YARD
     class ResponseTag < ::YARD::Tags::Tag
-      attr_accessor :schema
+      attr_accessor :content, :code
 
       # TODO: name == code. The name MUST be changed to code for better understanding
-      def initialize(tag_name, name, text, schema)
-        super(tag_name, text, nil, name)
-        @schema = schema
+      def initialize(tag_name, description, code, content)
+        super(tag_name, description, nil, nil)
+        @code = code
+        @content = content
       end
     end
   end

data/lib/oas_core.rb

@@ -3,6 +3,7 @@
 require 'yard'
 require 'method_source'
 require 'active_support/all'
+require 'deep_merge'
 
 module OasCore
   require 'oas_core/version'
@@ -49,11 +50,16 @@ module OasCore
   module YARD
     autoload :RequestBodyTag, 'oas_core/yard/request_body_tag'
     autoload :ExampleTag, 'oas_core/yard/example_tag'
+    autoload :ReferenceTag, 'oas_core/yard/reference_tag'
     autoload :RequestBodyExampleTag, 'oas_core/yard/request_body_example_tag'
     autoload :ParameterTag, 'oas_core/yard/parameter_tag'
     autoload :ResponseTag, 'oas_core/yard/response_tag'
     autoload :ResponseExampleTag, 'oas_core/yard/response_example_tag'
     autoload :OasCoreFactory, 'oas_core/yard/oas_core_factory'
+
+    autoload :ParameterReferenceTag, 'oas_core/yard/parameter_reference_tag'
+    autoload :RequestBodyReferenceTag, 'oas_core/yard/request_body_reference_tag'
+    autoload :ResponseReferenceTag, 'oas_core/yard/response_reference_tag'
   end
 
   class << self
@@ -71,9 +77,12 @@ module OasCore
       ::YARD::Tags::Library.default_factory = YARD::OasCoreFactory
       yard_tags = {
         'Request body' => %i[request_body with_request_body],
+        'Request body Reference' => %i[request_body_ref with_request_body_reference],
         'Request body Example' => %i[request_body_example with_request_body_example],
         'Parameter' => %i[parameter with_parameter],
+        'Parameter Reference' => %i[parameter_ref with_parameter_reference],
         'Response' => %i[response with_response],
+        'Response Reference' => %i[response_ref with_response_reference],
         'Response Example' => %i[response_example with_response_example],
         'Endpoint Tags' => [:tags],
         'Summary' => [:summary],
@@ -85,5 +94,11 @@ module OasCore
         ::YARD::Tags::Library.define_tag(tag_name, method_name, handler)
       end
     end
+
+    def build(oas_routes, oas_source: {})
+      oas = Builders::SpecificationBuilder.new.with_oas_routes(oas_routes).build.to_spec
+
+      oas_source.deep_merge(oas, merge_hash_arrays: true, extend_existing_arrays: true)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oas_core
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 1.0.0
 platform: ruby
 authors:
 - a-chacon
@@ -23,6 +23,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: deep_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
 - !ruby/object:Gem::Dependency
   name: method_source
   requirement: !ruby/object:Gem::Requirement
@@ -98,16 +118,22 @@ files:
 - lib/oas_core/version.rb
 - lib/oas_core/yard/example_tag.rb
 - lib/oas_core/yard/oas_core_factory.rb
+- lib/oas_core/yard/parameter_reference_tag.rb
 - lib/oas_core/yard/parameter_tag.rb
+- lib/oas_core/yard/reference_tag.rb
 - lib/oas_core/yard/request_body_example_tag.rb
+- lib/oas_core/yard/request_body_reference_tag.rb
 - lib/oas_core/yard/request_body_tag.rb
 - lib/oas_core/yard/response_example_tag.rb
+- lib/oas_core/yard/response_reference_tag.rb
 - lib/oas_core/yard/response_tag.rb
 homepage: https://github.com/a-chacon/oas_core
 licenses:
 - GPL-3.0-only
 metadata:
   homepage_uri: https://github.com/a-chacon/oas_core
+  source_code_uri: https://github.com/a-chacon/oas_core
+  changelog_uri: https://github.com/a-chacon/oas_core/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: