grape-oas 1.0.0

data/lib/grape_oas/api_model/operation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents an API operation (endpoint action) in the DTO model for OpenAPI v2/v3.
+    # Encapsulates HTTP method, parameters, request body, responses, tags, and security.
+    # Used as the core unit for both OpenAPIv2 and OpenAPIv3 operation objects.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Path
+    class Operation < Node
+      attr_accessor :http_method, :operation_id, :summary, :description,
+                    :deprecated, :parameters, :request_body,
+                    :responses, :tag_names, :security, :extensions,
+                    :consumes, :produces, :suppress_default_error_response
+
+      def initialize(http_method:, operation_id: nil, summary: nil, description: nil,
+                     deprecated: false, parameters: [], request_body: nil,
+                     responses: [], tag_names: [], security: [], extensions: nil,
+                     consumes: [], produces: [])
+        super()
+        @http_method   = http_method.to_s.downcase
+        @operation_id  = operation_id
+        @summary       = summary
+        @description   = description
+        @deprecated    = deprecated
+        @parameters    = Array(parameters)
+        @request_body  = request_body
+        @responses     = Array(responses)
+        @tag_names     = Array(tag_names)
+        @security      = Array(security)
+        @extensions    = extensions
+        @consumes      = Array(consumes)
+        @produces      = Array(produces)
+        @suppress_default_error_response = false
+      end
+
+      def add_parameter(parameter)
+        @parameters << parameter
+      end
+
+      def add_parameters(*parameters)
+        @parameters.concat(parameters)
+      end
+
+      def add_response(response)
+        @responses << response
+      end
+
+      def response(code)
+        @responses.find { |r| r.http_status == code.to_s }
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/parameter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents an operation parameter in the DTO model for OpenAPI v2/v3.
+    # Used for query, path, header, and cookie parameters in both OpenAPI versions.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Operation
+    class Parameter < Node
+      attr_accessor :location, :name, :required, :description, :schema, :collection_format
+
+      def initialize(location:, name:, schema:, required: false, description: nil, collection_format: nil)
+        super()
+        @location = location.to_s
+        @name = name
+        @required = required
+        @schema = schema
+        @description = description
+        @collection_format = collection_format
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/path.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents an API path (endpoint) in the DTO model for OpenAPI v2/v3.
+    # Contains a list of operations (HTTP methods) for the path.
+    # Used to build the 'paths' object in both OpenAPIv2 and OpenAPIv3 documents.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Api
+    class Path < Node
+      attr_accessor :template, :operations
+
+      def initialize(template:)
+        super()
+        @template   = template
+        @operations = []
+      end
+
+      def add_operation(operation)
+        @operations << operation
+      end
+
+      def [](method_sym)
+        @operations.find { |op| op.http_method.to_sym == method_sym.to_sym }
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/request_body.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents a request body in the DTO model for OpenAPI v2/v3.
+    # Used to describe the payload of HTTP requests, including content type and schema.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Operation
+    class RequestBody < Node
+      attr_accessor :description, :required, :media_types, :extensions, :body_name
+
+      def initialize(description: nil, required: false, media_types: [], extensions: nil, body_name: nil)
+        super()
+        @description = description
+        @required    = required
+        @media_types = Array(media_types)
+        @extensions  = extensions
+        @body_name   = body_name
+      end
+
+      def add_media_type(media_type)
+        @media_types << media_type
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents an HTTP response in the DTO model for OpenAPI v2/v3.
+    # Used to describe possible responses for an operation, including status, content, and headers.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Operation
+    class Response < Node
+      attr_accessor :http_status, :description, :media_types, :headers, :extensions, :examples
+
+      def initialize(http_status:, description:, media_types: [], headers: [], extensions: nil, examples: nil)
+        super()
+        @http_status = http_status.to_s
+        @description = description
+        @media_types = Array(media_types)
+        @headers     = Array(headers)
+        @extensions  = extensions
+        @examples    = examples
+      end
+
+      def add_media_type(media_type)
+        @media_types << media_type
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/schema.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents a schema object in the DTO model for OpenAPI v2/v3.
+    # Used to describe data types, properties, and structure for parameters, request bodies, and responses.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Parameter, GrapeOAS::ApiModel::RequestBody
+    class Schema < Node
+      VALID_ATTRIBUTES = %i[
+        canonical_name type format properties items description
+        required nullable enum additional_properties unevaluated_properties defs
+        examples extensions
+        min_length max_length pattern
+        minimum maximum exclusive_minimum exclusive_maximum
+        min_items max_items
+        discriminator all_of one_of any_of
+      ].freeze
+
+      attr_accessor(*VALID_ATTRIBUTES)
+
+      def initialize(**attrs)
+        super()
+
+        @properties = {}
+        @required = []
+        @nullable = false
+        @enum = nil
+        @additional_properties = nil
+        @unevaluated_properties = nil
+        @defs = {}
+        @discriminator = nil
+        @all_of = nil
+        @one_of = nil
+        @any_of = nil
+
+        attrs.each do |k, v|
+          unless VALID_ATTRIBUTES.include?(k)
+            raise ArgumentError, "Unknown Schema attribute: #{k}. Valid attributes: #{VALID_ATTRIBUTES.join(", ")}"
+          end
+
+          public_send("#{k}=", v)
+        end
+      end
+
+      def empty?
+        return false if @all_of&.any? || @one_of&.any? || @any_of&.any?
+
+        @properties.nil? || @properties.empty?
+      end
+
+      def add_property(name, schema, required: false)
+        @properties[name.to_s] = schema
+        @required << name.to_s if required
+        schema
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  class ApiModelBuilder
+    attr_reader :api
+
+    def initialize(options = {})
+      @api = GrapeOAS::ApiModel::API.new(
+        title: options.dig(:info, :title) || options[:title] || "Grape API",
+        version: options.dig(:info, :version) || options[:version] || "1",
+      )
+
+      @api.host = options[:host]
+      @api.base_path = normalize_base_path(options[:base_path])
+      @api.schemes = Array(options[:schemes]).compact
+      @api.security_definitions = options[:security_definitions] || {}
+      @api.security = options[:security] || []
+      @api.tag_defs.merge(Array(options[:tags])) if options[:tags]
+      @api.servers = build_servers(options)
+      @api.registered_schemas = build_registered_schemas(options[:models])
+      @api.suppress_default_error_response = options[:suppress_default_error_response] || false
+
+      @namespace_filter = options[:namespace]
+      @apis = []
+    end
+
+    def add_app(app)
+      GrapeOAS::ApiModelBuilders::Path
+        .new(api: @api, routes: app.routes, app: app, namespace_filter: @namespace_filter)
+        .build
+    end
+
+    private
+
+    def normalize_base_path(path)
+      return nil unless path
+
+      path.start_with?("/") ? path : "/#{path}"
+    end
+
+    def build_servers(options)
+      return options[:servers] if options[:servers]
+      return [] unless options[:host]
+
+      scheme = Array(options[:schemes]).compact.first || "https"
+      url = "#{scheme}://#{options[:host]}#{normalize_base_path(options[:base_path])}"
+      [{ "url" => url }]
+    end
+
+    # Build schemas from pre-registered models (entities/contracts)
+    # This allows adding models to definitions even if not referenced by endpoints
+    def build_registered_schemas(models)
+      return [] unless models
+
+      Array(models).map do |model|
+        model = model.constantize if model.is_a?(String)
+        GrapeOAS.introspectors.build_schema(model, stack: [], registry: {})
+      rescue StandardError
+        nil
+      end.compact
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/concerns/content_type_resolver.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module Concerns
+      # Shared module for resolving content types from routes, apps, and APIs.
+      # Used by both Operation and Response builders to avoid code duplication.
+      module ContentTypeResolver
+        private
+
+        def resolve_content_types
+          default_format = route_default_format_from_route || default_format_from_app_or_api
+          content_types = route_content_types_from_route
+          content_types ||= content_types_from_app_or_api(default_format)
+
+          mimes = []
+          if content_types.is_a?(Hash)
+            selected = content_types.select { |k, _| k.to_s.start_with?(default_format.to_s) } if default_format
+            selected = content_types if selected.nil? || selected.empty?
+            mimes = selected.values
+          elsif content_types.respond_to?(:to_a) && !content_types.is_a?(String)
+            mimes = content_types.to_a
+          end
+
+          mimes << mime_for_format(default_format) if mimes.empty? && default_format
+
+          mimes = mimes.map { |m| normalize_mime(m) }.compact
+          mimes.empty? ? [Constants::MimeTypes::JSON] : mimes.uniq
+        end
+
+        def mime_for_format(format)
+          return if format.nil?
+          return format if format.to_s.include?("/")
+
+          return unless defined?(Grape::ContentTypes::CONTENT_TYPES)
+
+          Grape::ContentTypes::CONTENT_TYPES[format.to_sym]
+        end
+
+        def normalize_mime(mime_or_format)
+          return nil if mime_or_format.nil?
+          return mime_or_format if mime_or_format.to_s.include?("/")
+
+          mime_for_format(mime_or_format)
+        end
+
+        def route_content_types_from_route
+          return route.settings[:content_types] || route.settings[:content_type] if route.respond_to?(:settings)
+
+          route.options[:content_types] || route.options[:content_type]
+        end
+
+        def route_default_format_from_route
+          return route.settings[:default_format] if route.respond_to?(:settings)
+
+          route.options[:format]
+        end
+
+        def default_format_from_app_or_api
+          return api.default_format if api.respond_to?(:default_format)
+          return app.default_format if app_responds_to?(:default_format)
+
+          api.settings[:default_format] if api.respond_to?(:settings) && api.settings[:default_format]
+        rescue NoMethodError
+          nil
+        end
+
+        def content_types_from_app_or_api(default_format)
+          source = if api.respond_to?(:content_types)
+                     api.content_types
+                   elsif app_responds_to?(:content_types)
+                     app.content_types
+                   elsif api.respond_to?(:settings)
+                     api.settings[:content_types]
+                   end
+
+          return nil unless source.is_a?(Hash)
+
+          return source unless default_format
+
+          filtered = source.select { |k, _| k.to_s.start_with?(default_format.to_s) }
+          filtered.empty? ? source : filtered
+        rescue NoMethodError
+          nil
+        end
+
+        def app_responds_to?(method)
+          !app.nil? && app.respond_to?(method)
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/concerns/oas_utilities.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module Concerns
+      # Shared utility methods for OpenAPI schema building.
+      module OasUtilities
+        # Regex pattern for valid Ruby constant names (used for entity resolution)
+        VALID_CONSTANT_PATTERN = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/
+
+        # Extracts OpenAPI extension fields (x-* prefixed keys) from a hash.
+        #
+        # @param hash [Hash] the source hash
+        # @return [Hash, nil] hash of extension fields, or nil if empty
+        def self.extract_extensions(hash)
+          return nil unless hash.is_a?(Hash)
+
+          ext = hash.select { |k, _| k.to_s.start_with?("x-") }
+          ext.empty? ? nil : ext
+        end
+
+        # Instance method version for including in classes
+        def extract_extensions(hash)
+          OasUtilities.extract_extensions(hash)
+        end
+
+        # Converts a CamelCase string to snake_case.
+        #
+        # @param str [String] the string to convert
+        # @return [String] the underscored string
+        def self.underscore(str)
+          str.gsub("::", "/")
+             .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .tr("-", "_")
+             .downcase
+        end
+
+        # Instance method version
+        def underscore(str)
+          OasUtilities.underscore(str)
+        end
+
+        # Simple pluralization (basic English rules).
+        #
+        # @param key [String] the string to pluralize
+        # @return [String] the pluralized string
+        def self.pluralize(key)
+          return "#{key}es" if key.end_with?("s", "x", "z", "ch", "sh")
+          return "#{key[0..-2]}ies" if key.end_with?("y") && !%w[a e i o u].include?(key[-2])
+
+          "#{key}s"
+        end
+
+        # Instance method version
+        def pluralize(key)
+          OasUtilities.pluralize(key)
+        end
+
+        # Checks if a string matches the valid Ruby constant pattern.
+        #
+        # @param str [String] the string to check
+        # @return [Boolean] true if valid constant name
+        def self.valid_constant_name?(str)
+          str.is_a?(String) && str.match?(VALID_CONSTANT_PATTERN)
+        end
+
+        # Instance method version
+        def valid_constant_name?(str)
+          OasUtilities.valid_constant_name?(str)
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/concerns/type_resolver.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module GrapeOAS
+  module ApiModelBuilders
+    module Concerns
+      # Centralizes Ruby type to OpenAPI schema type resolution.
+      # Used by request builders and introspectors to avoid duplicated type switching logic.
+      module TypeResolver
+        # Regex to match Grape's typed array notation like "[String]", "[Integer]"
+        TYPED_ARRAY_PATTERN = /^\[(\w+)\]$/
+
+        # Regex to match Grape's multi-type notation like "[String, Integer]", "[String, Float]"
+        MULTI_TYPE_PATTERN = /^\[(\w+(?:::\w+)*(?:,\s*\w+(?:::\w+)*)+)\]$/
+
+        # Resolves a Ruby class or type name to its OpenAPI schema type string.
+        # Handles both Ruby classes (Integer, Float) and string type names ("integer", "float").
+        # Also handles Grape's "[Type]" notation for typed arrays.
+        # Falls back to "string" for unknown types.
+        #
+        # @param type [Class, String, Symbol, nil] The type to resolve
+        # @return [String] The OpenAPI schema type
+        def resolve_schema_type(type)
+          return Constants::SchemaTypes::STRING if type.nil?
+
+          # Handle Ruby classes directly
+          if type.is_a?(Class)
+            # Check static mapping first
+            return Constants::RUBY_TYPE_MAPPING[type] if Constants::RUBY_TYPE_MAPPING.key?(type)
+
+            # Handle Grape::API::Boolean dynamically (may not be loaded at constant definition time)
+            return Constants::SchemaTypes::BOOLEAN if grape_boolean_type?(type)
+
+            return Constants::SchemaTypes::STRING
+          end
+
+          type_str = type.to_s
+
+          # Handle Grape's typed array notation like "[String]"
+          return Constants::SchemaTypes::ARRAY if type_str.match?(TYPED_ARRAY_PATTERN)
+
+          # Handle string/symbol type names
+          Constants::PRIMITIVE_TYPE_MAPPING.fetch(type_str.downcase, Constants::SchemaTypes::STRING)
+        end
+
+        # Checks if type is Grape's Boolean class (handles dynamic loading)
+        def grape_boolean_type?(type)
+          return false unless defined?(Grape::API::Boolean)
+
+          type == Grape::API::Boolean || type.to_s == "Grape::API::Boolean"
+        end
+
+        # Extracts the member type from Grape's "[Type]" notation.
+        # Returns nil if not a typed array.
+        #
+        # @param type [String] The type string to parse
+        # @return [String, nil] The inner type or nil
+        def extract_typed_array_member(type)
+          return nil unless type.is_a?(String)
+
+          match = type.match(TYPED_ARRAY_PATTERN)
+          match ? match[1] : nil
+        end
+
+        # Checks if type is a multi-type notation like "[String, Integer]"
+        #
+        # @param type [String] The type string to check
+        # @return [Boolean] true if multi-type notation
+        def multi_type?(type)
+          return false unless type.is_a?(String)
+
+          type.match?(MULTI_TYPE_PATTERN)
+        end
+
+        # Extracts individual types from Grape's multi-type notation "[String, Integer]"
+        # Returns nil if not a multi-type notation.
+        #
+        # @param type [String] The type string to parse
+        # @return [Array<String>, nil] Array of type names or nil
+        def extract_multi_types(type)
+          return nil unless type.is_a?(String)
+
+          match = type.match(MULTI_TYPE_PATTERN)
+          return nil unless match
+
+          match[1].split(/,\s*/)
+        end
+
+        # Builds a basic Schema object for the given Ruby primitive type.
+        # Handles special cases like Array and Hash.
+        # Note: Uses == instead of case/when because Ruby's === doesn't work for class equality
+        # (Array === Array returns false since Array is not an instance of Array)
+        #
+        # @param primitive [Class, nil] The Ruby primitive class
+        # @param member [Object, nil] For arrays, the member type
+        # @return [ApiModel::Schema] The schema object
+        def build_schema_for_primitive(primitive, member: nil)
+          if primitive == Array
+            items_schema = build_array_items_schema(member)
+            ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
+          elsif primitive == Hash
+            ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+          else
+            ApiModel::Schema.new(type: resolve_schema_type(primitive))
+          end
+        end
+
+        # Builds schema for array items, handling nested arrays recursively.
+        #
+        # @param member [Object, nil] The member type
+        # @return [ApiModel::Schema] The items schema
+        def build_array_items_schema(member)
+          return default_string_schema unless member
+
+          member_primitive, member_member = derive_primitive_and_member(member)
+          build_schema_for_primitive(member_primitive, member: member_member)
+        end
+
+        # Derives primitive type and nested member from a type.
+        # For Dry::Types, extracts the primitive and member type.
+        # For plain Ruby classes, returns the class with nil member.
+        #
+        # @param type [Object] The type to analyze
+        # @return [Array<Class, Object>] [primitive, member] tuple
+        def derive_primitive_and_member(type)
+          return [type, nil] unless type.respond_to?(:primitive)
+
+          primitive = type.primitive
+          member = type.respond_to?(:member) ? type.member : nil
+          [primitive, member]
+        end
+
+        private
+
+        def default_string_schema
+          ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
+        end
+      end
+    end
+  end
+end