Class: Schemable::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/schemable/definition.rb

Overview

The Definition class provides a blueprint for generating and modifying schemas. It includes methods for handling attributes, relationships, and various request and response attributes. The definition class is meant to be inherited by a class that represents a model. This class should be configured to match the model’s attributes and relationships. The default configuration is set in this class, but can be overridden in the model’s definition class.

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Definition

Returns a new instance of Definition.



13
14
15
 
# File 'lib/schemable/definition.rb', line 13

def initialize
  @configuration = Schemable.configuration
end

Instance Attribute Details

#additional_create_request_attributes ⇒ Hash

Returns the additional create request attributes that are not automatically generated. These attributes are appended to the create request schema.

Examples:

{ name: { type: :string } }

Returns:

  • (Hash) —

    The additional create request attributes that are not automatically generated (if any).



147
148
149
 
# File 'lib/schemable/definition.rb', line 147

def additional_create_request_attributes
  {}
end

#additional_update_request_attributes ⇒ Hash

Returns the additional update request attributes that are not automatically generated. These attributes are appended to the update request schema.

Examples:

{ name: { type: :string } }

Returns:

  • (Hash) —

    The additional update request attributes that are not automatically generated (if any).



158
159
160
 
# File 'lib/schemable/definition.rb', line 158

def additional_update_request_attributes
  {}
end

#configuration ⇒ Object (readonly)

Returns the value of attribute configuration.



10
11
12
 
# File 'lib/schemable/definition.rb', line 10

def configuration
  @configuration
end

#relationships ⇒ Hash

Note:

Note that the format of the relationships is as follows: {

belongs_to: { relationship_name: relationship_definition },
has_many: { relationship_name: relationship_definition },
addition_to_included: { relationship_name: relationship_definition }

}

Note:

The addition_to_included is used to define the extra nested relationships that are not defined in the belongs_to or has_many for included.

Returns the relationships defined in the serializer.

Examples:

{
  belongs_to: {
    district: Swagger::Definitions::District,
    user: Swagger::Definitions::User
  },
  has_many: {
    applicants: Swagger::Definitions::Applicant,
  },
  addition_to_included: {
    applicants: Swagger::Definitions::Applicant
  }
}

Returns:

  • (Hash) —

    The relationships defined in the serializer.



70
71
72
 
# File 'lib/schemable/definition.rb', line 70

def relationships
  { belongs_to: {}, has_many: {} }
end

Class Method Details

.generate ⇒ Array<Hash>

Returns the schema for the create request body, update request body, and response body.

Returns:

  • (Array<Hash>) —

    The schema for the create request body, update request body, and response body.



336
337
338
339
340
341
342
343
344
345
 
# File 'lib/schemable/definition.rb', line 336

def self.generate
  instance = new

  [
    "#{instance.model}CreateRequest": instance.camelize_keys(RequestSchemaGenerator.new(instance).generate_for_create),
    "#{instance.model}UpdateRequest": instance.camelize_keys(RequestSchemaGenerator.new(instance).generate_for_update),
    "#{instance.model}Response": instance.camelize_keys(ResponseSchemaGenerator.new(instance).generate(collection: true)),
    "#{instance.model}ResponseExpanded": instance.camelize_keys(ResponseSchemaGenerator.new(instance).generate(expand: true))
  ]
end

Instance Method Details

#additional_response_attributes ⇒ Hash

Returns the additional response attributes that are not automatically generated. These attributes are appended to the response schema.

Examples:

{ name: { type: :string } }

Returns:

  • (Hash) —

    The additional response attributes that are not automatically generated (if any).



168
169
170
 
# File 'lib/schemable/definition.rb', line 168

def additional_response_attributes
  {}
end

#additional_response_included ⇒ Hash

Returns the additional response included that are not automatically generated. These included additions are appended to the response schema’s included.

Examples:

{
  type: :object,
  properties: {
    id: { type: :string },
    type: { type: :string },
    attributes: {
      type: :object,
      properties: {
        name: { type: :string }
      }
    }
  }
}

Returns:

  • (Hash) —

    The additional response included that are not automatically generated (if any).



218
219
220
 
# File 'lib/schemable/definition.rb', line 218

def additional_response_included
  {}
end

#additional_response_relations ⇒ Hash

Returns the additional response relations that are not automatically generated. These relations are appended to the response schema’s relationships.

Examples:

{
  users: {
    type: :object,
    properties: {
      data: {
        type: :array,
        items: {
          type: :object,
          properties: {
            id: { type: :string },
            type: { type: :string }
          }
        }
      }
    }
  }
}

Returns:

  • (Hash) —

    The additional response relations that are not automatically generated (if any).



195
196
197
 
# File 'lib/schemable/definition.rb', line 195

def additional_response_relations
  {}
end

#array_types ⇒ Hash

Returns a hash of all the arrays defined for the model. The schema for each array is defined in the definition class manually. This method must be implemented in the definition class if there are any arrays.

Examples:

{
  metadata: {
      type: :array,
      items: {
          type: :object, nullable: true,
          properties: { name: { type: :string, nullable: true } }
      }
  }
}

Returns:

  • (Hash) —

    The arrays of the model and their schemas.



90
91
92
 
# File 'lib/schemable/definition.rb', line 90

def array_types
  {}
end

#attributes ⇒ Array<Symbol>

Returns the attributes for the definition based on the configuration. The attributes are inferred from the model’s attribute names by default. If the infer_attributes_from_custom_method configuration option is set, the attributes are inferred from the method specified. If the infer_attributes_from_jsonapi_serializable configuration option is set, the attributes are inferred from the serializer’s attribute blocks.

Examples:

attributes = definition.attributes # => [:id, :name, :email]

Returns:

  • (Array<Symbol>) —

    The attributes used for generating the schemas.



36
37
38
39
40
41
42
 
# File 'lib/schemable/definition.rb', line 36

def attributes
  return (serializer&.attribute_blocks&.transform_keys { |key| key.to_s.underscore.to_sym }&.keys || nil) if configuration.infer_attributes_from_jsonapi_serializable

  return model.send(configuration.infer_attributes_from_custom_method).map(&:to_sym) if configuration.infer_attributes_from_custom_method

  model.attribute_names.map(&:to_sym)
end

#camelize_keys(hash) ⇒ Hash, Array

Given a hash, it returns a new hash with all the keys camelized.

Examples:

{ first_name: 'John', last_name: 'Doe' } => { firstName: 'John', lastName: 'Doe' }

Parameters:

  • hash (Hash) —

    The hash with all the keys camelized.

Returns:

  • (Hash, Array) —

    The hash with all the keys camelized.



329
330
331
 
# File 'lib/schemable/definition.rb', line 329

def camelize_keys(hash)
  hash.deep_transform_keys { |key| key.to_s.camelize(:lower).to_sym }
end

#default_value_for_enum_attributes ⇒ Hash

Returns the default value for the enum attributes.

Examples:

{
  status: 'pending',
  flag: 0
}

Returns:

  • (Hash) —

    The custom default values for the enum attributes.



289
290
291
 
# File 'lib/schemable/definition.rb', line 289

def default_value_for_enum_attributes
  {}
end

#excluded_create_request_attributes ⇒ Array<Symbol>

Returns the attributes that are excluded from the create request schema. These attributes are not required or not needed to be present in the create request body.

Examples:

[:id, :updated_at, :created_at]

Returns:

  • (Array<Symbol>) —

    The attributes that are excluded from the create request schema.



229
230
231
 
# File 'lib/schemable/definition.rb', line 229

def excluded_create_request_attributes
  %i[]
end

#excluded_response_attributes ⇒ Array<Symbol>

Returns the attributes that are excluded from the update request schema. These attributes are not required or not needed to be present in the update request body.

Examples:

[:id, :updated_at, :created_at]

Returns:

  • (Array<Symbol>) —

    The attributes that are excluded from the update request schema.



251
252
253
 
# File 'lib/schemable/definition.rb', line 251

def excluded_response_attributes
  %i[]
end

#excluded_response_included ⇒ Array<Symbol>

TODO:

This method is not used anywhere yet.

Returns the included that are excluded from the response schema. These included are not needed to be present in the response body.

Examples:

[:users, :applicants]

Returns:

  • (Array<Symbol>) —

    The included that are excluded from the response schema.



276
277
278
 
# File 'lib/schemable/definition.rb', line 276

def excluded_response_included
  %i[]
end

#excluded_response_relations ⇒ Array<Symbol>

Returns the relationships that are excluded from the response schema. These relationships are not needed to be present in the response body.

Examples:

[:users, :applicants]

Returns:

  • (Array<Symbol>) —

    The relationships that are excluded from the response schema.



262
263
264
 
# File 'lib/schemable/definition.rb', line 262

def excluded_response_relations
  %i[]
end

#excluded_update_request_attributes ⇒ Array<Symbol>

Returns the attributes that are excluded from the response schema. These attributes are not needed to be present in the response body.

Examples:

[:id, :updated_at, :created_at]

Returns:

  • (Array<Symbol>) —

    The attributes that are excluded from the response schema.



240
241
242
 
# File 'lib/schemable/definition.rb', line 240

def excluded_update_request_attributes
  %i[]
end

#model ⇒ Class

Returns the model class (Constantized from the definition class name)

Examples:

User

Returns:

  • (Class) —

    The model class (Constantized from the definition class name)



306
307
308
 
# File 'lib/schemable/definition.rb', line 306

def model
  self.class.name.gsub('Swagger::Definitions::', '').constantize
end

#model_name ⇒ String

Returns the model name. Used for schema type naming.

Examples:

'users' for the User model
'citizen_applications' for the CitizenApplication model

Returns:

  • (String) —

    The model name.



317
318
319
 
# File 'lib/schemable/definition.rb', line 317

def model_name
  self.class.name.gsub('Swagger::Definitions::', '').pluralize.underscore.downcase
end

#nullable_attributes ⇒ Array<Symbol>

Returns the attributes that are nullable in the request/response body. This means that they can be present in the request/response body but they can be null. They are not required to be present in the request body.

Examples:

[:name, :email]

Returns:

  • (Array<Symbol>) —

    The attributes that are nullable in the request/response body.



124
125
126
 
# File 'lib/schemable/definition.rb', line 124

def nullable_attributes
  %i[]
end

#nullable_relationships ⇒ Array<String>

Returns the relationships that are nullable in the response body. This means that they can be present in the response body but they can be null. They are not required to be present in the request body.

Examples:

['users', 'applicant']

Returns:

  • (Array<String>) —

    The attributes that are nullable in the response body.



136
137
138
 
# File 'lib/schemable/definition.rb', line 136

def nullable_relationships
  %w[]
end

#optional_create_request_attributes ⇒ Array<Symbol>

Attributes that are not required in the create request.

Examples:

optional_create_request_attributes = definition.optional_create_request_attributes
# => [:email]

Returns:

  • (Array<Symbol>) —

    The attributes that are not required in the create request.



101
102
103
 
# File 'lib/schemable/definition.rb', line 101

def optional_create_request_attributes
  %i[]
end

#optional_update_request_attributes ⇒ Array<Symbol>

Attributes that are not required in the update request.

Examples:

optional_update_request_attributes = definition.optional_update_request_attributes
# => [:email]

Returns:

  • (Array<Symbol>) —

    The attributes that are not required in the update request.



112
113
114
 
# File 'lib/schemable/definition.rb', line 112

def optional_update_request_attributes
  %i[]
end

#serialized_instance ⇒ Hash

Returns an instance of the model class that is already serialized into jsonapi format.

Returns:

  • (Hash) —

    The serialized instance of the model class.



296
297
298
 
# File 'lib/schemable/definition.rb', line 296

def serialized_instance
  {}
end

#serializer ⇒ JSONAPI::Serializable::Resource?

Returns the serializer of the model for the definition.

Examples:

UsersSerializer

Returns:

  • (JSONAPI::Serializable::Resource, nil) —

    The model’s serializer.

Raises:

  • (NotImplementedError) 


21
22
23
24
25
 
# File 'lib/schemable/definition.rb', line 21

def serializer
  raise NotImplementedError, 'You must implement the serializer method in the definition class in order to use the infer_serializer_from_jsonapi_serializable configuration option.' if configuration.infer_attributes_from_jsonapi_serializable

  nil
end