grape-oas 1.0.0

data/lib/grape_oas/api_model_builders/operation.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    class Operation
+      include Concerns::ContentTypeResolver
+      include Concerns::OasUtilities
+
+      attr_reader :api, :route, :app, :path_param_name_map, :template_override
+
+      def initialize(api:, route:, app: nil, path_param_name_map: nil, template_override: nil)
+        @api = api
+        @route = route
+        @app = app
+        @path_param_name_map = path_param_name_map || {}
+        @template_override = template_override
+      end
+
+      def build
+        operation = GrapeOAS::ApiModel::Operation.new(
+          http_method: http_method,
+          operation_id: operation_id,
+          summary: route.options[:description],
+          description: build_description,
+          tag_names: tag_names,
+          extensions: operation_extensions,
+          consumes: consumes,
+          produces: produces,
+          deprecated: build_deprecated,
+        )
+        operation.suppress_default_error_response = build_suppress_default_error_response
+
+        api.add_tags(*tag_names) if tag_names.any?
+
+        build_request(operation)
+
+        build_responses.each { |resp| operation.add_response(resp) }
+        ensure_path_parameters(operation)
+
+        operation.security = build_security if build_security
+
+        operation
+      end
+
+      private
+
+      def operation_id
+        @operation_id ||= route.options.fetch(:nickname) do
+          slug = route
+                 .pattern
+                 .origin
+                 .gsub(/[^a-z0-9]+/i, "_")
+                 .gsub(/_+/, "_")
+                 .sub(/^_|_$/, "")
+
+          "#{http_method}_#{slug}"
+        end
+      end
+
+      def http_method
+        @http_method ||= route.request_method.downcase.to_sym
+      end
+
+      def tag_names
+        @tag_names ||= Array(route.options[:tags]).presence || derive_tag_from_path
+      end
+
+      # Derive tag from path when no explicit tags are defined (like grape-swagger's tag_object)
+      def derive_tag_from_path
+        path = template_override || sanitize_route_path(route.path)
+        # Remove path parameters like {id} and {version}
+        path_without_params = path.gsub(/\{[^}]+\}/, "")
+        segments = path_without_params.split("/").reject(&:empty?)
+
+        # Remove prefix and version from segments
+        prefix_segments = route_prefix_segments
+        version_segments = route_version_segments
+
+        filtered = segments.reject { |s| prefix_segments.include?(s) || version_segments.include?(s) }
+
+        Array(filtered.first).presence || []
+      end
+
+      def route_prefix_segments
+        prefix = route.prefix.to_s
+        prefix.split("/").reject(&:empty?)
+      end
+
+      def route_version_segments
+        version = route.version
+        Array(version).map(&:to_s)
+      end
+
+      def build_response
+        GrapeOAS::ApiModelBuilders::Response
+          .new(api: api, route: route, app: app)
+          .build
+      end
+
+      def build_responses
+        Array(build_response)
+      end
+
+      def build_security
+        route.options.dig(:documentation, :security) ||
+          route.options[:security] ||
+          route.options[:auth]
+      end
+
+      def build_deprecated
+        route.options[:deprecated] ||
+          route.options.dig(:documentation, :deprecated) ||
+          false
+      end
+
+      def build_suppress_default_error_response
+        route.options[:suppress_default_error_response] ||
+          route.options.dig(:documentation, :suppress_default_error_response) ||
+          false
+      end
+
+      def build_description
+        route.options[:detail] ||
+          route.options.dig(:documentation, :desc)
+      end
+
+      def consumes
+        resolve_content_types
+      end
+
+      def produces
+        resolve_content_types
+      end
+
+      def operation_extensions
+        extract_extensions(route.options[:documentation])
+      end
+
+      def build_request(operation)
+        GrapeOAS::ApiModelBuilders::Request
+          .new(api: api, route: route, operation: operation, path_param_name_map: path_param_name_map)
+          .build
+      end
+
+      # Ensure every {param} in the path template has a corresponding path parameter.
+      def ensure_path_parameters(operation)
+        template = template_override || sanitize_route_path(route.path)
+        placeholders = template.scan(/\{([^}]+)\}/).flatten
+        existing = Array(operation.parameters).select { |p| p.location == "path" }.map(&:name)
+        missing = placeholders - existing
+        missing.each do |name|
+          operation.add_parameter(
+            GrapeOAS::ApiModel::Parameter.new(
+              location: "path",
+              name: name,
+              required: true,
+              schema: GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::STRING),
+            ),
+          )
+        end
+      end
+
+      def sanitize_route_path(path)
+        path.gsub(Path::EXTENSION_PATTERN, "").gsub(Path::PATH_PARAMETER_PATTERN, "{\\k<param>}")
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/path.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    class Path
+      # Matches format extensions like (.json), (.:format), (.json)(.:format)
+      EXTENSION_PATTERN = /(\(\.[^)]+\))+$/
+      private_constant :EXTENSION_PATTERN
+
+      PATH_PARAMETER_PATTERN = %r{(?<=/):(?<param>[^/]+)}
+      private_constant :PATH_PARAMETER_PATTERN
+
+      NORMALIZED_PLACEHOLDER = /\{[^}]+\}/
+      private_constant :NORMALIZED_PLACEHOLDER
+
+      attr_reader :api, :routes, :app, :namespace_filter
+
+      def initialize(api:, routes:, app: nil, namespace_filter: nil)
+        @api = api
+        @routes = routes
+        @app = app
+        @namespace_filter = namespace_filter
+      end
+
+      def build
+        canonical_paths = {}
+
+        @routes.each_with_object({}) do |route, api_routes|
+          next if skip_route?(route)
+
+          route_path = sanitize_path(route.path)
+          normalized = normalize_template(route_path)
+
+          canonical_info = canonical_paths[normalized]
+          path_param_name_map = nil
+
+          if canonical_info
+            path_param_name_map = map_param_names(canonical_info[:template], route_path)
+            route_path = canonical_info[:template]
+          else
+            canonical_paths[normalized] = { template: route_path }
+          end
+
+          api_path = api_routes.fetch(route_path) do
+            path = GrapeOAS::ApiModel::Path.new(template: route_path)
+            api_routes[route_path] = path
+
+            api.add_path(path)
+
+            path
+          end
+
+          operation = build_operation(route, path_param_name_map: path_param_name_map, template_override: route_path)
+
+          api_path.add_operation(operation)
+        end
+      end
+
+      private
+
+      def skip_route?(route)
+        return true if filtered_by_namespace?(route)
+
+        # Check route_setting :swagger, hidden: true
+        route_hidden = route.settings.dig(:swagger, :hidden)
+        # Check desc "...", swagger: { hidden: true }
+        route_hidden = route.options.dig(:swagger, :hidden) if route.options.dig(:swagger, :hidden)
+        # Direct hidden option takes precedence (from desc hidden: or verb method options)
+        route_hidden = route.options[:hidden] if route.options.key?(:hidden)
+
+        # Support callable objects (Proc/lambda) for conditional hiding
+        route_hidden = route_hidden.call if route_hidden.respond_to?(:call)
+
+        route_hidden
+      end
+
+      # Returns true if route should be filtered out due to namespace filter.
+      # Routes are included if their path matches the namespace exactly or starts with namespace followed by "/".
+      def filtered_by_namespace?(route)
+        return false unless namespace_filter
+
+        route_path = sanitize_path(route.path)
+        namespace_prefix = namespace_filter.start_with?("/") ? namespace_filter : "/#{namespace_filter}"
+
+        # Match exact namespace or namespace followed by / or {
+        return false if route_path == namespace_prefix
+        return false if route_path.start_with?("#{namespace_prefix}/")
+
+        true
+      end
+
+      def build_operation(route, path_param_name_map: nil, template_override: nil)
+        GrapeOAS::ApiModelBuilders::Operation
+          .new(api: api, route: route, app: app, path_param_name_map: path_param_name_map, template_override: template_override)
+          .build
+      end
+
+      def sanitize_path(path)
+        path
+          .gsub(EXTENSION_PATTERN, "") # Remove format extensions like (.json)
+          .gsub(PATH_PARAMETER_PATTERN, "{\\k<param>}") # Replace named parameters with curly braces
+      end
+
+      def normalize_template(path)
+        sanitize_path(path).gsub(NORMALIZED_PLACEHOLDER, "{}")
+      end
+
+      def map_param_names(canonical_template, incoming_template)
+        canonical_params = canonical_template.scan(/\{([^}]+)\}/).flatten
+        incoming_params = incoming_template.scan(/\{([^}]+)\}/).flatten
+        return nil unless canonical_params.length == incoming_params.length
+
+        mapping = incoming_params.zip(canonical_params).to_h
+        # Only return mapping when names differ to avoid needless work
+        mapping if mapping.any? && mapping.keys != mapping.values
+      end
+
+      public_constant :EXTENSION_PATTERN
+      public_constant :PATH_PARAMETER_PATTERN
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/request.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require_relative "concerns/type_resolver"
+
+module GrapeOAS
+  module ApiModelBuilders
+    class Request
+      include Concerns::TypeResolver
+      include Concerns::OasUtilities
+
+      attr_reader :api, :route, :operation, :path_param_name_map
+
+      def initialize(api:, route:, operation:, path_param_name_map: nil)
+        @api = api
+        @route = route
+        @operation = operation
+        @path_param_name_map = path_param_name_map || {}
+      end
+
+      def build
+        body_schema, route_params = GrapeOAS::ApiModelBuilders::RequestParams
+                                    .new(api: api, route: route, path_param_name_map: path_param_name_map)
+                                    .build
+
+        contract_schema = build_contract_schema
+        body_schema = contract_schema if contract_schema
+
+        operation.add_parameters(*route_params)
+        append_request_body(body_schema) unless body_schema.empty?
+      end
+
+      private
+
+      def append_request_body(body_schema)
+        # OAS spec says GET/HEAD/DELETE "MAY ignore" request bodies
+        # Skip by default unless explicitly allowed via documentation option
+        http_method = operation.http_method.to_s.downcase
+        if %w[get head delete].include?(http_method)
+          allow_body = route.options.dig(:documentation, :request_body) ||
+                       route.options[:request_body]
+          return unless allow_body
+        end
+
+        media_ext = media_type_extensions(Constants::MimeTypes::JSON)
+
+        # Set canonical_name if not already set (e.g., DryIntrospector may have set it for polymorphism)
+        if body_schema.respond_to?(:canonical_name) && body_schema.canonical_name.nil?
+          settings = route.respond_to?(:settings) ? route.settings : {}
+          contract_class = route.options[:contract] || route.options[:schema] || settings[:contract]
+
+          if contract_class.is_a?(Class) && defined?(Menti::Endpoint::Schema) && contract_class < Menti::Endpoint::Schema
+            body_schema.canonical_name = contract_class.name
+          elsif contract_class # some other contract (e.g., Dry); keep inline
+            # no-op
+          elsif body_schema.properties.values.any? { |prop| prop.respond_to?(:canonical_name) && prop.canonical_name }
+            # keep entity/property refs intact; don't override
+          elsif operation.respond_to?(:operation_id) && operation.operation_id
+            body_schema.canonical_name = "#{operation.operation_id}_Request"
+          end
+        end
+
+        media_types = Array(operation.consumes.presence || [Constants::MimeTypes::JSON]).map do |mime|
+          GrapeOAS::ApiModel::MediaType.new(
+            mime_type: mime,
+            schema: body_schema,
+            extensions: media_ext,
+          )
+        end
+        operation.request_body = GrapeOAS::ApiModel::RequestBody.new(
+          required: body_schema.required && !body_schema.required.empty?,
+          media_types: media_types,
+          extensions: request_body_extensions,
+          body_name: route.options[:body_name],
+        )
+      end
+
+      def documentation_options
+        route.options[:documentation] || {}
+      end
+
+      def request_body_extensions
+        extract_extensions(documentation_options)
+      end
+
+      def media_type_extensions(mime)
+        content = documentation_options[:content]
+        return nil unless content.is_a?(Hash)
+
+        mt = content[mime] || content[mime.to_sym]
+        extract_extensions(mt)
+      end
+
+      def build_contract_schema
+        settings = route.respond_to?(:settings) ? route.settings : {}
+        contract = route.options[:contract] || settings[:contract]
+        return unless contract
+
+        schema_obj = if contract.respond_to?(:schema)
+                       contract.schema
+                     elsif contract.respond_to?(:call)
+                       contract
+                     end
+
+        # Pass the contract class (not schema_obj) so DryIntrospector can detect inheritance
+        return GrapeOAS::Introspectors::DryIntrospector.build(contract) if schema_obj.respond_to?(:types)
+
+        contract_hash = if contract.respond_to?(:to_h)
+                          contract.to_h
+                        elsif contract.respond_to?(:schema) && contract.schema.respond_to?(:to_h)
+                          contract.schema.to_h
+                        end
+        return unless contract_hash.is_a?(Hash)
+
+        hash_to_schema(contract_hash)
+      end
+
+      def hash_to_schema(obj)
+        schema = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+        obj.each do |key, value|
+          case value
+          when Hash
+            schema.add_property(key, hash_to_schema(value))
+          when Array
+            item_schema = if value.first.is_a?(Hash)
+                            hash_to_schema(value.first)
+                          else
+                            GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
+                          end
+            schema.add_property(key, GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: item_schema))
+          else
+            prop_schema = GrapeOAS::ApiModel::Schema.new(type: map_type(value))
+            prop_schema.nullable = true if value.nil?
+            schema.add_property(key, prop_schema)
+          end
+        end
+        schema
+      end
+
+      def map_type(value)
+        return value.primitive.to_s.downcase if value.respond_to?(:primitive)
+
+        # First try direct lookup (for Ruby class values like String, Integer)
+        # Then try class-based lookup (for actual runtime values like "hello", 123)
+        Constants::RUBY_TYPE_MAPPING.fetch(value) do
+          Constants::RUBY_TYPE_MAPPING.fetch(value.class, Constants::SchemaTypes::STRING)
+        end
+      end
+
+      def schema_from_types(types_hash, rule_constraints)
+        schema = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+        types_hash.each do |name, dry_type|
+          prop_schema = schema_for_type(dry_type)
+          merge_rule_constraints(prop_schema, rule_constraints[name]) if rule_constraints[name]
+          required = true
+          required = false if dry_type.respond_to?(:optional?) && dry_type.optional?
+          required = false if dry_type.respond_to?(:meta) && dry_type.meta[:omittable]
+          schema.add_property(name, prop_schema, required: required)
+        end
+        schema
+      end
+
+      def schema_for_type(dry_type)
+        if dry_type.respond_to?(:primitive) && dry_type.primitive == Array && dry_type.respond_to?(:member)
+          items_schema = schema_for_type(dry_type.member)
+          schema = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
+          apply_array_meta_constraints(schema, dry_type.respond_to?(:meta) ? dry_type.meta : {})
+          return schema
+        end
+
+        primitive, member = derive_primitive_and_member(dry_type)
+        if dry_type.respond_to?(:primitive) && dry_type.primitive == Array
+          member ||= dry_type.respond_to?(:member) ? dry_type.member : nil
+          primitive = Array
+        end
+        meta = dry_type.respond_to?(:meta) ? dry_type.meta : {}
+        nullable = dry_type.respond_to?(:optional?) && dry_type.optional?
+        enum_vals = dry_type.respond_to?(:values) ? dry_type.values : nil
+
+        schema = if primitive == Array
+                   items_schema = member ? schema_for_type(member) : default_string_schema
+                   s = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
+                   apply_array_meta_constraints(s, meta)
+                   s
+                 else
+                   build_schema_for_primitive(primitive)
+                 end
+
+        schema.nullable = nullable
+        schema.enum = enum_vals if enum_vals
+        apply_string_meta_constraints(schema, meta) if primitive == String
+        apply_numeric_meta_constraints(schema, meta) if [Integer, Float, BigDecimal].include?(primitive)
+        schema
+      end
+
+      def derive_primitive_and_member(dry_type)
+        if defined?(Dry::Types::Array::Member) && dry_type.respond_to?(:type) && dry_type.type.is_a?(Dry::Types::Array::Member)
+          return [Array, dry_type.type.member]
+        end
+
+        return [Array, dry_type.member] if dry_type.respond_to?(:member)
+
+        primitive = dry_type.respond_to?(:primitive) ? dry_type.primitive : nil
+        [primitive, nil]
+      end
+
+      def apply_string_meta_constraints(schema, meta)
+        min_length = extract_min_constraint(meta)
+        max_length = extract_max_constraint(meta)
+        schema.min_length = min_length if min_length
+        schema.max_length = max_length if max_length
+        schema.pattern = meta[:pattern] if meta[:pattern]
+      end
+
+      def apply_array_meta_constraints(schema, meta)
+        min_items = extract_min_constraint(meta, :min_items)
+        max_items = extract_max_constraint(meta, :max_items)
+        schema.min_items = min_items if min_items
+        schema.max_items = max_items if max_items
+      end
+
+      # Extract minimum constraint, supporting multiple key names
+      def extract_min_constraint(meta, specific_key = :min_length)
+        meta[:min_size] || meta[specific_key]
+      end
+
+      # Extract maximum constraint, supporting multiple key names
+      def extract_max_constraint(meta, specific_key = :max_length)
+        meta[:max_size] || meta[specific_key]
+      end
+
+      def apply_numeric_meta_constraints(schema, meta)
+        if meta[:gt]
+          schema.minimum = meta[:gt]
+          schema.exclusive_minimum = true
+        elsif meta[:gteq]
+          schema.minimum = meta[:gteq]
+        end
+        if meta[:lt]
+          schema.maximum = meta[:lt]
+          schema.exclusive_maximum = true
+        elsif meta[:lteq]
+          schema.maximum = meta[:lteq]
+        end
+      end
+
+      def merge_rule_constraints(schema, rule_constraints)
+        return unless rule_constraints
+
+        schema.enum ||= rule_constraints[:enum]
+        schema.nullable ||= rule_constraints[:nullable]
+        schema.min_length ||= rule_constraints[:min] if rule_constraints[:min]
+        schema.max_length ||= rule_constraints[:max] if rule_constraints[:max]
+        schema.minimum ||= rule_constraints[:minimum] if rule_constraints[:minimum]
+        schema.maximum ||= rule_constraints[:maximum] if rule_constraints[:maximum]
+        schema.exclusive_minimum ||= rule_constraints[:exclusive_minimum]
+        schema.exclusive_maximum ||= rule_constraints[:exclusive_maximum]
+      end
+
+      # Very small parser for FakeType rule_ast used in tests
+      def extract_rule_constraints(schema_obj)
+        return {} unless schema_obj.respond_to?(:rules)
+
+        # Only supports FakeSchema/FakeType used in tests
+        constraints = Hash.new { |h, k| h[k] = {} }
+        if schema_obj.respond_to?(:types)
+          schema_obj.types.each do |name, dry_type|
+            next unless dry_type.respond_to?(:rule_ast)
+
+            rules = dry_type.rule_ast
+            Array(rules).each do |rule|
+              next unless rule.is_a?(Array)
+
+              _, pred = rule
+              next unless pred.is_a?(Array)
+
+              pname, pargs = pred
+              case pname
+              when :size?
+                min, max = Array(pargs).first
+                constraints[name][:min] = min
+                constraints[name][:max] = max
+              when :maybe
+                constraints[name][:nullable] = true
+              end
+            end
+          end
+        end
+        constraints
+      rescue NoMethodError, TypeError
+        {}
+      end
+
+      def extract_enum_from_core_values(core)
+        return unless core.respond_to?(:values)
+
+        vals = core.values
+        vals if vals.is_a?(Array)
+      rescue NoMethodError
+        nil
+      end
+    end
+  end
+end