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



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

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:



112
113
114
115
 
# File 'lib/verquest/base/public_class_methods.rb', line 112

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



95
96
97
98
99
100
101
102
103
 
# File 'lib/verquest/base/public_class_methods.rb', line 95

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, ...

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, Exception) —

    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
 
# 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

  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
    mapped_params = version_class.map_params(params)

    case Verquest.configuration.validation_error_handling
    when :raise
      mapped_params
    when :result
      Result.success(mapped_params)
    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



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

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



50
51
52
 
# File 'lib/verquest/base/public_class_methods.rb', line 50

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



59
60
61
62
63
64
65
66
67
 
# File 'lib/verquest/base/public_class_methods.rb', line 59

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



73
74
75
 
# File 'lib/verquest/base/public_class_methods.rb', line 73

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:



86
87
88
 
# File 'lib/verquest/base/public_class_methods.rb', line 86

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