schemable 0.1.3 → 1.0.0

data/lib/schemable/attribute_schema_generator.rb

@@ -0,0 +1,130 @@
+module Schemable
+  # The AttributeSchemaGenerator class is responsible for generating JSON schemas for model attributes.
+  # It includes methods for generating the overall schema and individual attribute schemas.
+  #
+  # @see Schemable
+  class AttributeSchemaGenerator
+    attr_reader :model_definition, :configuration, :model, :schema_modifier, :response
+
+    # Initializes a new AttributeSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    # @example
+    #   generator = AttributeSchemaGenerator.new(model_definition)
+    def initialize(model_definition)
+      @model_definition = model_definition
+      @model = model_definition.model
+      @configuration = Schemable.configuration
+      @schema_modifier = SchemaModifier.new
+      @response = nil
+    end
+
+    # Generates the JSON schema for the model attributes.
+    #
+    # @return [Hash] The generated schema.
+    # @example
+    #   schema = generator.generate
+    def generate
+      schema = {
+        type: :object,
+        properties: @model_definition.attributes.index_with do |attr|
+          generate_attribute_schema(attr)
+        end
+      }
+
+      # Rename enum attributes to remove the suffix or prefix if mongoid is used
+      if @configuration.orm == :mongoid
+        schema[:properties].transform_keys! do |key|
+          key.to_s.gsub(@configuration.enum_prefix_for_simple_enum || @configuration.enum_suffix_for_simple_enum, '')
+        end
+      end
+
+      # modify the schema to include additional response relations
+      schema = @schema_modifier.add_properties(schema, @model_definition.additional_response_attributes, 'properties')
+
+      # modify the schema to exclude response relations
+      @model_definition.excluded_response_attributes.each do |key|
+        schema = @schema_modifier.delete_properties(schema, "properties.#{key}")
+      end
+
+      schema
+    end
+
+    # Generates the JSON schema for a specific attribute.
+    #
+    # @param attribute [Symbol, String] The attribute to generate the schema for.
+    # @return [Hash] The generated schema for the attribute.
+    # @example
+    #   attribute_schema = generator.generate_attribute_schema(:attribute_name)
+    def generate_attribute_schema(attribute)
+      if @configuration.orm == :mongoid
+        # Get the column hash for the attribute
+        attribute_hash = @model.fields[attribute.to_s]
+
+        # Check if this attribute has a custom JSON Schema definition
+        return @model_definition.array_types[attribute] if @model_definition.array_types.keys.include?(attribute.to_sym)
+        return @model_definition.additional_response_attributes[attribute] if @model_definition.additional_response_attributes.keys.include?(attribute)
+
+        # Check if this is an array attribute
+        return @configuration.type_mapper(:array) if attribute_hash.try(:[], 'options').try(:[], 'type') == 'Array'
+
+        # Check if this is an enum attribute
+        @response = if attribute_hash.name.end_with?('_cd')
+                      @configuration.type_mapper(:string)
+                    else
+                      # Map the column type to a JSON Schema type if none of the above conditions are met
+                      @configuration.type_mapper(attribute_hash.try(:type).to_s.downcase.to_sym)
+                    end
+
+      elsif @configuration.orm == :active_record
+        # Get the column hash for the attribute
+        attribute_hash = @model.columns_hash[attribute.to_s]
+
+        # Check if this attribute has a custom JSON Schema definition
+        return @model_definition.array_types[attribute] if @model_definition.array_types.keys.include?(attribute.to_sym)
+        return @model_definition.additional_response_attributes[attribute] if @model_definition.additional_response_attributes.keys.include?(attribute)
+
+        # Check if this is an array attribute
+        return @configuration.type_mapper(:array) if attribute_hash.as_json.try(:[], 'sql_type_metadata').try(:[], 'sql_type').include?('[]')
+
+        # Map the column type to a JSON Schema type if none of the above conditions are met
+        @response = @configuration.type_mapper(attribute_hash.try(:type))
+
+      else
+        raise 'ORM not supported'
+      end
+
+      # If the attribute is nullable, modify the schema accordingly
+      return @schema_modifier.add_properties(@response, { nullable: true }, '.') if @response && @model_definition.nullable_attributes.include?(attribute)
+
+      # If attribute is an enum, modify the schema accordingly
+      if @configuration.custom_defined_enum_method && @model.respond_to?(@configuration.custom_defined_enum_method)
+        defined_enums = @model.send(@configuration.custom_defined_enum_method)
+        enum_attribute = attribute.to_s.gsub(@configuration.enum_prefix_for_simple_enum || @configuration.enum_suffix_for_simple_enum, '').to_s
+        return @schema_modifier.add_properties(@response, { enum: defined_enums[enum_attribute].keys }, '.') if @response && defined_enums[enum_attribute].present?
+      elsif @model.respond_to?(:defined_enums)
+        return @schema_modifier.add_properties(@response, { enum: @model.defined_enums[attribute.to_s].keys }, '.') if @response && @model.defined_enums.key?(attribute.to_s)
+      end
+
+      return @response unless @response.nil?
+
+      # If we haven't found a schema type yet, try to infer it from the type of the attribute's value in the instance data
+      if @configuration.use_serialized_instance
+        serialized_instance = @model_definition.serialized_instance
+
+        type_from_instance = serialized_instance.as_json['data']['attributes'][attribute.to_s.camelize(:lower)]&.class&.name&.downcase
+
+        @response = @configuration.type_mapper(type_from_instance) if type_from_instance.present?
+
+        return @response unless @response.nil?
+      end
+
+      # If we still haven't found a schema type, default to object
+      @configuration.type_mapper(:object)
+    rescue NoMethodError
+      # Log a warning if the attribute does not exist on the @model
+      Rails.logger.warn("\e[33mWARNING: #{@model} does not have an attribute named \e[31m#{attribute}\e[0m")
+      {}
+    end
+  end
+end

data/lib/schemable/configuration.rb

@@ -0,0 +1,114 @@
+module Schemable
+  # The Configuration class provides a set of configuration options for the Schemable module.
+  # It includes options for setting the ORM, handling enums, custom type mappers, and more.
+  # It is worth noting that the configuration options are global, and will affect all Definitions.
+  #
+  # @see Schemable
+  class Configuration
+    attr_accessor(
+      :orm,
+      :float_as_string,
+      :decimal_as_string,
+      :pagination_enabled,
+      :custom_type_mappers,
+      :use_serialized_instance,
+      :custom_defined_enum_method,
+      :enum_prefix_for_simple_enum,
+      :enum_suffix_for_simple_enum,
+      :custom_meta_response_schema,
+      :infer_attributes_from_custom_method,
+      :infer_attributes_from_jsonapi_serializable
+    )
+
+    # Initializes a new Configuration instance with default values.
+    def initialize
+      @orm = :active_record # orm options are :active_record, :mongoid
+      @float_as_string = false
+      @custom_type_mappers = {}
+      @pagination_enabled = true
+      @decimal_as_string = false
+      @use_serialized_instance = false
+      @custom_defined_enum_method = nil
+      @custom_meta_response_schema = nil
+      @enum_prefix_for_simple_enum = nil
+      @enum_suffix_for_simple_enum = nil
+      @infer_attributes_from_custom_method = nil
+      @infer_attributes_from_jsonapi_serializable = false
+    end
+
+    # Returns a type mapper for a given type name.
+    #
+    # @note If a custom type mapper is defined for the given type name, it will be returned.
+    #
+    # @example
+    #   type_mapper(:string) #=> { type: :string }
+    #
+    # @param type_name [Symbol, String] The name of the type.
+    # @return [Hash] The type mapper for the given type name.
+    def type_mapper(type_name)
+      return @custom_type_mappers[type_name] if @custom_type_mappers.key?(type_name.to_sym)
+
+      {
+        text: { type: :string },
+        string: { type: :string },
+        symbol: { type: :string },
+        integer: { type: :integer },
+        boolean: { type: :boolean },
+        date: { type: :string, format: :date },
+        time: { type: :string, format: :time },
+        json: { type: :object, properties: {} },
+        hash: { type: :object, properties: {} },
+        jsonb: { type: :object, properties: {} },
+        object: { type: :object, properties: {} },
+        binary: { type: :string, format: :binary },
+        trueclass: { type: :boolean, default: true },
+        falseclass: { type: :boolean, default: false },
+        datetime: { type: :string, format: :'date-time' },
+        big_decimal: { type: (@decimal_as_string ? :string : :number).to_s.to_sym, format: :double },
+        'bson/objectid': { type: :string, format: :object_id },
+        'mongoid/boolean': { type: :boolean },
+        'mongoid/stringified_symbol': { type: :string },
+        'active_support/time_with_zone': { type: :string, format: :date_time },
+        float: {
+          type: (@float_as_string ? :string : :number).to_s.to_sym,
+          format: :float
+        },
+        decimal: {
+          type: (@decimal_as_string ? :string : :number).to_s.to_sym,
+          format: :double
+        },
+        array: {
+          type: :array,
+          items: {
+            anyOf: [
+              { type: :string },
+              { type: :integer },
+              { type: :boolean },
+              { type: :number, format: :float },
+              { type: :object, properties: {} },
+              { type: :number, format: :double }
+            ]
+          }
+        }
+      }[type_name.to_s.underscore.try(:to_sym)]
+    end
+
+    # Adds a custom type mapper for a given type name.
+    #
+    # @example
+    #  add_custom_type_mapper(:custom_type, { type: :custom })
+    #  type_mapper(:custom_type) #=> { type: :custom }
+    #
+    #  # It preferable to invoke this method in the config/initializers/schemable.rb file.
+    #  # This way, the custom type mapper will be available for all Definitions.
+    #  Schemable.configure do |config|
+    #   config.add_custom_type_mapper(:custom_type, { type: :custom })
+    #  end
+    #
+    # @param type_name [Symbol, String] The name of the type.
+    # @param mapping [Hash] The mapping to add.
+    def add_custom_type_mapper(type_name, mapping)
+      custom_type_mappers[type_name.to_sym] = mapping
+    end
+  end
+end

data/lib/schemable/definition.rb

@@ -0,0 +1,322 @@
+module Schemable
+  # 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 Schemable
+  class Definition
+    attr_reader :configuration
+    attr_writer :relationships, :additional_create_request_attributes, :additional_update_request_attributes
+
+    def initialize
+      @configuration = Schemable.configuration
+    end
+
+    # Returns the serializer of the model for the definition.
+    # @example
+    #   UsersSerializer
+    # @return [JSONAPI::Serializable::Resource, nil] The model's serializer.
+    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
+
+    # 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.
+    #
+    # @example
+    #   attributes = definition.attributes # => [:id, :name, :email]
+    #
+    # @return [Array<Symbol>] The attributes used for generating the schemas.
+    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
+
+    # Returns the relationships defined in the serializer.
+    #
+    # @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.
+    #
+    # @example
+    #  {
+    #    belongs_to: {
+    #      district: Swagger::Definitions::District,
+    #      user: Swagger::Definitions::User
+    #    },
+    #    has_many: {
+    #      applicants: Swagger::Definitions::Applicant,
+    #    },
+    #    addition_to_included: {
+    #      applicants: Swagger::Definitions::Applicant
+    #    }
+    #  }
+    #
+    # @return [Hash] The relationships defined in the serializer.
+    def relationships
+      { belongs_to: {}, has_many: {} }
+    end
+
+    # 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.
+    #
+    # @return [Hash] The arrays of the model and their schemas.
+    #
+    # @example
+    #  {
+    #    metadata: {
+    #        type: :array,
+    #        items: {
+    #            type: :object, nullable: true,
+    #            properties: { name: { type: :string, nullable: true } }
+    #        }
+    #    }
+    #  }
+    def array_types
+      {}
+    end
+
+    # Attributes that are not required in the create request.
+    #
+    # @example
+    #   optional_create_request_attributes = definition.optional_create_request_attributes
+    #   # => [:email]
+    #
+    # @return [Array<Symbol>] The attributes that are not required in the create request.
+    def optional_create_request_attributes
+      %i[]
+    end
+
+    # Attributes that are not required in the update request.
+    #
+    # @example
+    #   optional_update_request_attributes = definition.optional_update_request_attributes
+    #   # => [:email]
+    #
+    # @return [Array<Symbol>] The attributes that are not required in the update request.
+    def optional_update_request_attributes
+      %i[]
+    end
+
+    # 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.
+    #
+    # @example
+    #  [:name, :email]
+    #
+    # @return [Array<Symbol>] The attributes that are nullable in the request/response body.
+    def nullable_attributes
+      %i[]
+    end
+
+    # Returns the additional create request attributes that are not automatically generated.
+    # These attributes are appended to the create request schema.
+    #
+    # @example
+    #  { name: { type: :string } }
+    #
+    # @return [Hash] The additional create request attributes that are not automatically generated (if any).
+    def additional_create_request_attributes
+      {}
+    end
+
+    # Returns the additional update request attributes that are not automatically generated.
+    # These attributes are appended to the update request schema.
+    #
+    # @example
+    #  { name: { type: :string } }
+    #
+    # @return [Hash] The additional update request attributes that are not automatically generated (if any).
+    def additional_update_request_attributes
+      {}
+    end
+
+    # Returns the additional response attributes that are not automatically generated. These attributes are appended to the response schema.
+    #
+    # @example
+    #  { name: { type: :string } }
+    #
+    # @return [Hash] The additional response attributes that are not automatically generated (if any).
+    def additional_response_attributes
+      {}
+    end
+
+    # Returns the additional response relations that are not automatically generated.
+    # These relations are appended to the response schema's relationships.
+    #
+    # @example
+    #  {
+    #    users: {
+    #      type: :object,
+    #      properties: {
+    #        data: {
+    #          type: :array,
+    #          items: {
+    #            type: :object,
+    #            properties: {
+    #              id: { type: :string },
+    #              type: { type: :string }
+    #            }
+    #          }
+    #        }
+    #      }
+    #    }
+    #  }
+    #
+    # @return [Hash] The additional response relations that are not automatically generated (if any).
+    def additional_response_relations
+      {}
+    end
+
+    # Returns the additional response included that are not automatically generated.
+    # These included additions are appended to the response schema's included.
+    #
+    # @example
+    #  {
+    #    type: :object,
+    #    properties: {
+    #      id: { type: :string },
+    #      type: { type: :string },
+    #      attributes: {
+    #        type: :object,
+    #        properties: {
+    #          name: { type: :string }
+    #        }
+    #      }
+    #    }
+    #  }
+    #
+    # @return [Hash] The additional response included that are not automatically generated (if any).
+    def additional_response_included
+      {}
+    end
+
+    # 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.
+    #
+    # @example
+    #  [:id, :updated_at, :created_at]
+    #
+    # @return [Array<Symbol>] The attributes that are excluded from the create request schema.
+    def excluded_create_request_attributes
+      %i[]
+    end
+
+    # Returns the attributes that are excluded from the response schema.
+    # These attributes are not needed to be present in the response body.
+    #
+    # @example
+    #  [:id, :updated_at, :created_at]
+    #
+    # @return [Array<Symbol>] The attributes that are excluded from the response schema.
+    def excluded_update_request_attributes
+      %i[]
+    end
+
+    # 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.
+    #
+    # @example
+    #  [:id, :updated_at, :created_at]
+    #
+    # @return [Array<Symbol>] The attributes that are excluded from the update request schema.
+    def excluded_response_attributes
+      %i[]
+    end
+
+    # Returns the relationships that are excluded from the response schema.
+    # These relationships are not needed to be present in the response body.
+    #
+    # @example
+    #  [:users, :applicants]
+    #
+    # @return [Array<Symbol>] The relationships that are excluded from the response schema.
+    def excluded_response_relations
+      %i[]
+    end
+
+    # Returns the included that are excluded from the response schema.
+    # These included are not needed to be present in the response body.
+    #
+    # @example
+    #  [:users, :applicants]
+    #
+    # @todo
+    #  This method is not used anywhere yet.
+    #
+    # @return [Array<Symbol>] The included that are excluded from the response schema.
+    def excluded_response_included
+      %i[]
+    end
+
+    # Returns an instance of the model class that is already serialized into jsonapi format.
+    #
+    # @return [Hash] The serialized instance of the model class.
+    def serialized_instance
+      {}
+    end
+
+    # Returns the model class (Constantized from the definition class name)
+    #
+    # @example
+    #  User
+    #
+    # @return [Class] The model class (Constantized from the definition class name)
+    def model
+      self.class.name.gsub('Swagger::Definitions::', '').constantize
+    end
+
+    # Returns the model name. Used for schema type naming.
+    #
+    # @return [String] The model name.
+    #
+    # @example
+    #  'users' for the User model
+    #  'citizen_applications' for the CitizenApplication model
+    def model_name
+      self.class.name.gsub('Swagger::Definitions::', '').pluralize.underscore.downcase
+    end
+
+    # Given a hash, it returns a new hash with all the keys camelized.
+    #
+    # @param hash [Hash] The hash with all the keys camelized.
+    #
+    # @return [Hash, Array] The hash with all the keys camelized.
+    #
+    # @example
+    #  { first_name: 'John', last_name: 'Doe' } => { firstName: 'John', lastName: 'Doe' }
+    def camelize_keys(hash)
+      hash.deep_transform_keys { |key| key.to_s.camelize(:lower).to_sym }
+    end
+
+    # Returns the schema for the create request body, update request body, and response body.
+    #
+    # @return [Array<Hash>] The schema for the create request body, update request body, and response body.
+    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
+  end
+end

data/lib/schemable/included_schema_generator.rb

@@ -0,0 +1,107 @@
+module Schemable
+  # The IncludedSchemaGenerator class is responsible for generating the 'included' part of a JSON:API compliant response.
+  # This class generates schemas for related resources that should be included in the response.
+  #
+  # @see Schemable
+  class IncludedSchemaGenerator
+    attr_reader :model_definition, :schema_modifier, :relationships
+
+    # Initializes a new IncludedSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    #
+    # @example
+    #   generator = IncludedSchemaGenerator.new(model_definition)
+    def initialize(model_definition)
+      @model_definition = model_definition
+      @schema_modifier = SchemaModifier.new
+      @relationships = @model_definition.relationships
+    end
+
+    # Generates the 'included' part of the JSON:API response.
+    # It iterates over each relationship type (belongs_to, has_many) and for each relationship,
+    # it prepares a schema. If the 'expand' option is true, it also includes the relationships of the related resource in the schema.
+    # In that case, the 'addition_to_included' relationships are also included in the schema unless they are excluded from expansion.
+    #
+    # @param expand [Boolean] Whether to include the relationships of the related resource in the schema.
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from the schema.
+    #
+    # @note Make sure to provide the names correctly in string format and pluralize them if necessary.
+    #       For example, if you have a relationship named 'applicant', and an applicant has association
+    #       named 'identity', you should provide 'identities' as the names of the relationship to exclude from expansion.
+    #       In this case, the included schema of the applicant will not include the identity relationship.
+    #
+    # @example
+    #   schema = generator.generate(expand: true, relationships_to_exclude_from_expansion: ['some_relationship'])
+    #
+    # @return [Hash] The generated schema.
+    def generate(expand: false, relationships_to_exclude_from_expansion: [])
+      return {} if @relationships.blank?
+      return {} if @relationships == { belongs_to: {}, has_many: {} }
+
+      definitions = []
+
+      %i[belongs_to has_many addition_to_included].each do |relation_type|
+        next if @relationships[relation_type].blank?
+
+        definitions << @relationships[relation_type].values
+      end
+
+      definitions.flatten!
+
+      included_schemas = definitions.map do |definition|
+        next if relationships_to_exclude_from_expansion.include?(definition.model_name)
+
+        if expand
+          definition_relations = definition.relationships[:belongs_to].values.map(&:model_name) + definition.relationships[:has_many].values.map(&:model_name)
+          relations_to_exclude = []
+          definition_relations.each do |relation|
+            relations_to_exclude << relation if relationships_to_exclude_from_expansion.include?(relation)
+          end
+
+          prepare_schema_for_included(definition, expand:, relationships_to_exclude_from_expansion: relations_to_exclude)
+        else
+          prepare_schema_for_included(definition)
+        end
+      end
+
+      schema = {
+        included: {
+          type: :array,
+          items: {
+            anyOf: included_schemas.compact_blank
+          }
+        }
+      }
+
+      @schema_modifier.add_properties(schema, @model_definition.additional_response_included, 'included.items') if @model_definition.additional_response_included.present?
+
+      schema
+    end
+
+    # Prepares the schema for a related resource to be included in the response.
+    # It generates the attribute and relationship schemas for the related resource and combines them into a single schema.
+    #
+    # @param model_definition [ModelDefinition] The model definition of the related resource.
+    # @param expand [Boolean] Whether to include the relationships of the related resource in the schema.
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from the schema.
+    #
+    # @example
+    #   included_schema = generator.prepare_schema_for_included(related_model_definition, expand: true, relationships_to_exclude_from_expansion: ['some_relationship'])
+    #
+    # @return [Hash] The generated schema for the related resource.
+    def prepare_schema_for_included(model_definition, expand: false, relationships_to_exclude_from_expansion: [])
+      attributes_schema = AttributeSchemaGenerator.new(model_definition).generate
+      relationships_schema = RelationshipSchemaGenerator.new(model_definition).generate(relationships_to_exclude_from_expansion:, expand:)
+
+      {
+        type: :object,
+        properties: {
+          type: { type: :string, default: model_definition.model_name },
+          id: { type: :string },
+          attributes: attributes_schema
+        }.merge!(relationships_schema.blank? ? {} : { relationships: relationships_schema })
+      }.compact_blank
+    end
+  end
+end