Module: Verquest::Base::PublicClassMethods

Included in:
Verquest::Base
Defined in:
lib/verquest/base/public_class_methods.rb

Overview

Public class methods to be included in Verquest::Base

This module contains class methods that handle parameter mapping, schema generation, and validation functionality for Verquest API request objects.

Instance Method Summary collapse

Instance Method Details

#component_name ⇒ String

Returns the component name derived from the class name. It is used in JSON schema references.

Returns:

  • (String) —

    The component name



139
140
141
 
# File 'lib/verquest/base/public_class_methods.rb', line 139

def component_name
  name.to_s.split("::", 2).last.tr("::", "")
end

#external_mapping(version: nil) ⇒ Hash

Returns the external mapping for a specific version

This method returns a mapping hash that translates from internal attribute names back to external parameter names.

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

Returns:

  • (Hash) —

    The inverted mapping configuration where keys are internal names and values are external names

See Also:



121
122
123
124
 
# File 'lib/verquest/base/public_class_methods.rb', line 121

def external_mapping(version: nil)
  version = resolve(version)
  version.external_mapping
end

#mapping(version: nil, property: nil) ⇒ Hash

Returns the mapping for a specific version or property

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

  • property (String, Symbol, nil) (defaults to: nil) —

    Specific property to retrieve mapping for

Returns:

  • (Hash) —

    The mapping configuration



104
105
106
107
108
109
110
111
112
 
# File 'lib/verquest/base/public_class_methods.rb', line 104

def mapping(version: nil, property: nil)
  version = resolve(version)

  if property
    version.mapping_for(property)
  else
    version.mapping
  end
end

#process(params, version: nil, validate: nil, remove_extra_root_keys: nil) ⇒ Verquest::Result, Hash

Maps incoming parameters to the appropriate structure based on version mapping

Parameters:

  • params (Hash) —

    The parameters to be mapped

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

  • validate (Boolean, nil) (defaults to: nil) —

    Whether to validate the params, defaults to configuration setting

  • remove_extra_root_keys (Boolean, nil) (defaults to: nil) —

    Whether to remove extra keys at the root level, defaults to configuration setting

Returns:

  • (Verquest::Result, Hash) —

    When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors. When validation_error_handling is :raise, returns mapped params directly or raises InvalidParamsError with validation errors.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/verquest/base/public_class_methods.rb', line 17

def process(params, version: nil, validate: nil, remove_extra_root_keys: nil)
  validate = Verquest.configuration.validate_params if validate.nil?
  remove_extra_root_keys = Verquest.configuration.remove_extra_root_keys if remove_extra_root_keys.nil?

  version_class = resolve(version)

  params = params.dup
  params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
  params = params.slice(*version_class.properties.keys) if remove_extra_root_keys && !version_class.combination?

  if validate && (validation_result = version_class.validate_params(params: params)) && validation_result.any?
    case Verquest.configuration.validation_error_handling
    when :raise
      raise InvalidParamsError.new("Validation failed", errors: validation_result)
    when :result
      Result.failure(validation_result)
    end
  else
    begin
      mapped_params = version_class.map_params(params)

      case Verquest.configuration.validation_error_handling
      when :raise
        mapped_params
      when :result
        Result.success(mapped_params)
      end
    rescue MappingError => e
      case Verquest.configuration.validation_error_handling
      when :raise
        raise
      when :result
        Result.failure([{message: e.message, type: "mapping_error"}])
      end
    end
  end
end

#to_ref(property: nil) ⇒ String

Returns the JSON reference for the request or a specific property

Parameters:

  • property (String, Symbol, nil) (defaults to: nil) —

    Specific property to retrieve reference for

Returns:

  • (String) —

    The JSON reference for the request or property



130
131
132
133
134
 
# File 'lib/verquest/base/public_class_methods.rb', line 130

def to_ref(property: nil)
  base = "#/components/schemas/#{component_name}"

  property ? "#{base}/properties/#{property}" : base
end

#to_schema(version: nil) ⇒ Hash

Returns the JSON schema for the request

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

Returns:

  • (Hash) —

    The JSON schema for the request



59
60
61
 
# File 'lib/verquest/base/public_class_methods.rb', line 59

def to_schema(version: nil)
  resolve(version).schema
end

#to_validation_schema(version: nil, property: nil) ⇒ Hash

Returns the validation JSON schema for the request or a specific property. It contains all schemas from references.

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

  • property (Symbol, nil) (defaults to: nil) —

    Specific property to retrieve schema for

Returns:

  • (Hash) —

    The validation schema or property schema



68
69
70
71
72
73
74
75
76
 
# File 'lib/verquest/base/public_class_methods.rb', line 68

def to_validation_schema(version: nil, property: nil)
  version = resolve(version)

  if property
    version.validation_schema["properties"][property.to_s]
  else
    version.validation_schema
  end
end

#valid_schema?(version: nil) ⇒ Boolean

Validates the generated JSON schema structure

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

Returns:

  • (Boolean) —

    True if schema is valid



82
83
84
 
# File 'lib/verquest/base/public_class_methods.rb', line 82

def valid_schema?(version: nil)
  resolve(version).valid_schema?
end

#validate_schema(version: nil) ⇒ Array<Hash>

Validates the schema against the metaschema and returns detailed validation errors

This method validates the schema against the configured JSON Schema metaschema and returns detailed validation errors if any are found. It’s useful for debugging schema issues during development and testing.

Parameters:

  • version (String, nil) (defaults to: nil) —

    Specific version to use, defaults to configuration setting

Returns:

  • (Array<Hash>) —

    An array of validation error details, empty if schema is valid

See Also:



95
96
97
 
# File 'lib/verquest/base/public_class_methods.rb', line 95

def validate_schema(version: nil)
  resolve(version).validate_schema
end