jsonapi_compliable 0.6.13 → 0.7.2

data/docs/top-level-namespace.html

@@ -82,7 +82,7 @@
 <p class="children">
   
     
-      <strong class="modules">Modules:</strong> <span class='object_link'><a href="JsonapiCompliable.html" title="JsonapiCompliable (module)">JsonapiCompliable</a></span>
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Jsonapi.html" title="Jsonapi (module)">Jsonapi</a></span>, <span class='object_link'><a href="JsonapiCompliable.html" title="JsonapiCompliable (module)">JsonapiCompliable</a></span>
     
   
     
@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Fri May  5 15:53:21 2017 by
+  Generated on Wed Jun  7 10:15:09 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.9 (ruby-2.3.0).
 </div>

data/lib/generators/jsonapi/resource_generator.rb

@@ -2,85 +2,166 @@ module Jsonapi
   class ResourceGenerator < ::Rails::Generators::NamedBase
     source_root File.expand_path('../templates', __FILE__)
 
-    class_option :'no-controller', type: :boolean, default: false
-    class_option :'no-serializer', type: :boolean, default: false
-    class_option :'no-payload', type: :boolean, default: false
-    class_option :'no-strong-resources', type: :boolean, default: false
-    class_option :'no-test', type: :boolean, default: false
-
-    desc "This generator creates a resource file at app/resources"
+    class_option :'omit-comments',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-comments', '-c'],
+      desc: 'Generate without documentation comments'
+    class_option :'omit-controller',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-controller'],
+      desc: 'Generate without controller'
+    class_option :'omit-serializer',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-serializer', '-s'],
+      desc: 'Generate without serializer'
+    class_option :'omit-payload',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-payload', '-p'],
+      desc: 'Generate without spec payload'
+    class_option :'omit-strong-resource',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-strong-resource', '-r'],
+      desc: 'Generate without strong resource'
+    class_option :'omit-route',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-route'],
+      desc: 'Generate without specs'
+    class_option :'omit-tests',
+      type: :boolean,
+      default: false,
+      aliases: ['--omit-tests', '-t'],
+      desc: 'Generate without specs'
+
+    desc "This generator creates a resource file at app/resources, as well as corresponding controller/specs/route/etc"
     def copy_resource_file
-      unless @options['no-controller']
-        to = File.join('app/controllers', class_path, "#{file_name.pluralize}_controller.rb")
-        template('controller.rb.erb', to)
+      unless model_klass
+        raise "You must define a #{class_name} model before generating the corresponding resource."
       end
 
-      unless @options['no-serializer']
-        to = File.join('app/serializers', class_path, "serializable_#{file_name}.rb")
-        template('serializer.rb.erb', to)
-      end
+      generate_controller unless omit_controller?
+      generate_serializer unless omit_serializer?
+      generate_application_resource unless application_resource_defined?
+      generate_spec_payload unless omit_spec_payload?
+      generate_strong_resource unless omit_strong_resource?
+      generate_route unless omit_route?
+      generate_tests unless omit_tests?
+      generate_resource
+    end
 
-      unless 'ApplicationResource'.safe_constantize
-        to = File.join('app/resources', class_path, "application_resource.rb")
-        template('application_resource.rb.erb', to)
-      end
+    private
 
-      unless @options['no-payload']
-        to = File.join('spec/payloads', class_path, "#{file_name}.rb")
-        template('payload.rb.erb', to)
-      end
+    def omit_comments?
+      @options['omit-comments']
+    end
+
+    def generate_controller
+      to = File.join('app/controllers', class_path, "#{file_name.pluralize}_controller.rb")
+      template('controller.rb.erb', to)
+    end
 
-      unless @options['no-strong-resources']
-        inject_into_file 'config/initializers/strong_resources.rb', after: "StrongResources.configure do\n" do <<-STR
+    def omit_controller?
+      @options['omit-controller']
+    end
+
+    def generate_serializer
+      to = File.join('app/serializers', class_path, "serializable_#{file_name}.rb")
+      template('serializer.rb.erb', to)
+    end
+
+    def omit_serializer?
+      @options['omit-serializer']
+    end
+
+    def generate_application_resource
+      to = File.join('app/resources', class_path, "application_resource.rb")
+      template('application_resource.rb.erb', to)
+    end
+
+    def application_resource_defined?
+      'ApplicationResource'.safe_constantize.present?
+    end
+
+    def generate_spec_payload
+      to = File.join('spec/payloads', class_path, "#{file_name}.rb")
+      template('payload.rb.erb', to)
+    end
+
+    def omit_spec_payload?
+      @options['no-payload']
+    end
+
+    def generate_strong_resource
+      code = <<-STR
   strong_resource :#{file_name} do
     # Your attributes go here, e.g.
     # attribute :name, :string
   end
 
-        STR
-        end
+      STR
+      inject_into_file 'config/initializers/strong_resources.rb', after: "StrongResources.configure do\n" do
+        code
       end
+    end
+
+    def omit_strong_resource?
+      @options['no-strong-resources']
+    end
 
-      unless @options['no-route']
-        inject_into_file 'config/routes.rb', after: "scope '/api' do\n    scope '/v1' do\n" do <<-STR
+    def generate_route
+      code = <<-STR
       resources :#{type}
-        STR
-        end
+      STR
+      inject_into_file 'config/routes.rb', after: "scope path: '/api' do\n    scope path: '/v1' do\n" do
+        code
       end
+    end
 
-      unless @options['no-test']
-        to = File.join "spec/api/v1/#{file_name.pluralize}",
-          class_path,
-          "index_spec.rb"
-        template('index_request_spec.rb.erb', to)
-
-        to = File.join "spec/api/v1/#{file_name.pluralize}",
-          class_path,
-          "show_spec.rb"
-        template('show_request_spec.rb.erb', to)
-
-        to = File.join "spec/api/v1/#{file_name.pluralize}",
-          class_path,
-          "create_spec.rb"
-        template('create_request_spec.rb.erb', to)
-
-        to = File.join "spec/api/v1/#{file_name.pluralize}",
-          class_path,
-          "update_spec.rb"
-        template('update_request_spec.rb.erb', to)
-
-        to = File.join "spec/api/v1/#{file_name.pluralize}",
-          class_path,
-          "destroy_spec.rb"
-        template('destroy_request_spec.rb.erb', to)
-      end
+    def omit_route?
+      @options['no-route']
+    end
+
+    def generate_tests
+      to = File.join "spec/api/v1/#{file_name.pluralize}",
+        class_path,
+        "index_spec.rb"
+      template('index_request_spec.rb.erb', to)
+
+      to = File.join "spec/api/v1/#{file_name.pluralize}",
+        class_path,
+        "show_spec.rb"
+      template('show_request_spec.rb.erb', to)
+
+      to = File.join "spec/api/v1/#{file_name.pluralize}",
+        class_path,
+        "create_spec.rb"
+      template('create_request_spec.rb.erb', to)
+
+      to = File.join "spec/api/v1/#{file_name.pluralize}",
+        class_path,
+        "update_spec.rb"
+      template('update_request_spec.rb.erb', to)
+
+      to = File.join "spec/api/v1/#{file_name.pluralize}",
+        class_path,
+        "destroy_spec.rb"
+      template('destroy_request_spec.rb.erb', to)
+    end
 
+    def omit_tests?
+      @options['no-test']
+    end
+
+    def generate_resource
       to = File.join('app/resources', class_path, "#{file_name}_resource.rb")
       template('resource.rb.erb', to)
     end
 
-    private
-
     def model_klass
       class_name.safe_constantize
     end

data/lib/generators/jsonapi/templates/application_resource.rb.erb

@@ -1,5 +1,14 @@
-require 'jsonapi_compliable/adapters/active_record'
-
+<%- unless omit_comments? -%>
+# ApplicationResource is similar to ApplicationRecord - a base class that
+# holds configuration/methods for subclasses.
+# All Resources should inherit from ApplicationResource.
+# Resource documentation: https://jsonapi-suite.github.io/jsonapi_compliable/JsonapiCompliable/Resource.html
+<%- end -%>
 class ApplicationResource < JsonapiCompliable::Resource
+  <%- unless omit_comments? -%>
+  # Use the ActiveRecord Adapter for all subclasses.
+  # Subclasses can still override this default.
+  # More on adapters: https://jsonapi-suite.github.io/jsonapi_compliable/JsonapiCompliable/Adapters/Abstract.html
+  <%- end -%>
   use_adapter JsonapiCompliable::Adapters::ActiveRecord
 end

data/lib/generators/jsonapi/templates/controller.rb.erb

@@ -1,21 +1,46 @@
 <% module_namespacing do -%>
 class <%= model_klass.name.pluralize %>Controller < ApplicationController
+  <%- unless omit_comments? -%>
+  # Mark this as a JSONAPI controller, associating with the given resource
+  <%- end -%>
   jsonapi resource: <%= model_klass %>Resource
 
+  <%- unless omit_comments? -%>
+  # Reference a strong resource payload defined in
+  # config/initializers/strong_resources.rb
+  <%- end -%>
   strong_resource :<%= file_name %>
 
+  <%- unless omit_comments? -%>
+  # Run strong parameter validation for these actions.
+  # Invalid keys will be dropped.
+  # Invalid value types will log or raise based on the configuration
+  # ActionController::Parameters.action_on_invalid_parameters
+  <%- end -%>
   before_action :apply_strong_params, only: [:create, :update]
 
+  <%- unless omit_comments? -%>
+  # Start with a base scope and pass to render_jsonapi
+  <%- end -%>
   def index
     <%= file_name.pluralize %> = <%= model_klass %>.all
     render_jsonapi(<%= file_name.pluralize %>)
   end
 
+  <%- unless omit_comments? -%>
+  # Call jsonapi_scope directly here so we can get behavior like
+  # sparse fieldsets and statistics.
+  <%- end -%>
   def show
     scope = jsonapi_scope(<%= model_klass %>.where(id: params[:id]))
     render_jsonapi(scope.resolve.first, scope: false)
   end
 
+  <%- unless omit_comments? -%>
+  # jsonapi_create will use the configured Resource (and adapter) to persist.
+  # This will handle nested relationships as well.
+  # On validation errors, render correct error JSON.
+  <%- end -%>
   def create
     <%= file_name %>, success = jsonapi_create.to_a
 
@@ -26,6 +51,11 @@ class <%= model_klass.name.pluralize %>Controller < ApplicationController
     end
   end
 
+  <%- unless omit_comments? -%>
+  # jsonapi_update will use the configured Resource (and adapter) to persist.
+  # This will handle nested relationships as well.
+  # On validation errors, render correct error JSON.
+  <%- end -%>
   def update
     <%= file_name %>, success = jsonapi_update.to_a
 
@@ -36,6 +66,10 @@ class <%= model_klass.name.pluralize %>Controller < ApplicationController
     end
   end
 
+  <%- unless omit_comments? -%>
+  # No need for any special logic here as no_content is jsonapi_compliant.
+  # Customize this if you have a more complex use case.
+  <%- end -%>
   def destroy
     <%= file_name %> = <%= model_klass %>.find(params[:id])
     <%= file_name %>.destroy

data/lib/generators/jsonapi/templates/destroy_request_spec.rb.erb

@@ -2,7 +2,7 @@ require 'rails_helper'
 
 RSpec.describe "<%= type %>#destroy", type: :request do
   context 'basic destroy' do
-    let!(:<%= file_name %>) { create(:<%= file_name %>) }
+    let!(:<%= file_name %>) { FactoryGirl.create(:<%= file_name %>) }
 
     it 'updates the resource' do
       expect {

data/lib/generators/jsonapi/templates/payload.rb.erb

@@ -1,2 +1,33 @@
+<%- unless omit_comments? -%>
+# Register a payload to validate against.
+# Add expected attributes within this block, e.g.:
+#
+# key(:name)
+#
+# Optionally validate the type as well:
+#
+# key(:name, String)
+#
+# This will:
+#
+# * Compare record.name == json['name']
+# * Ensure no extra keys are in the json payload
+# * Ensure no values are nil (unless allow_nil: true is passed)
+# * Ensures json['name'] is a string
+#
+# If you have custom serialization logic and want to compare against
+# something other than "record.name", pass a block:
+#
+# key(:name) { |record| record.name.upcase }
+#
+# Or, if this is a one-off for a particular spec, do that customization at
+# runtime:
+#
+# assert_payload(:person, person_record, json_item) do
+#   key(:name) { 'Homer Simpson' }
+# end
+#
+# For more information, see https://jsonapi-suite.github.io/jsonapi_spec_helpers/
+<%- end -%>
 JsonapiSpecHelpers::Payload.register(:<%= file_name %>) do
 end

data/lib/generators/jsonapi/templates/resource.rb.erb

@@ -1,6 +1,53 @@
+<%- unless omit_comments? -%>
+# Define how to query and persist a given model.
+# Further Resource documentation: https://jsonapi-suite.github.io/jsonapi_compliable/JsonapiCompliable/Resource.html
+<%- end -%>
 <% module_namespacing do -%>
 class <%= class_name %>Resource < ApplicationResource
+  <%- unless omit_comments? -%>
+  # Used for associating this resource with a given input.
+  # This should match the 'type' in the corresponding serializer.
+  <%- end -%>
   type :<%= type %>
+  <%- unless omit_comments? -%>
+  # Associate to a Model object so we know how to persist.
+  <%- end -%>
   model <%= model_klass %>
+  <%- unless omit_comments? -%>
+  # Customize your resource here. Some common examples:
+  #
+  # === Allow ?filter[name] query parameter ===
+  # allow_filter :name
+  #
+  # === Enable total count, when requested ===
+  # allow_stat total: [:count]
+  #
+  # === Allow sideloading/sideposting of relationships ===
+  # belongs_to :foo,
+  #   foreign_key: :foo_id,
+  #   resource: FooResource,
+  #   scope: -> { Foo.all }
+  #
+  # === Custom sorting logic ===
+  # sort do |scope, att, dir|
+  #   ... code ...
+  # end
+  #
+  # === Change default sort ===
+  # default_sort([{ title: :asc }])
+  #
+  # === Custom pagination logic ===
+  # paginate do |scope, current_page, per_page|
+  #   ... code ...
+  # end
+  #
+  # === Change default page size ===
+  # default_page_size(10)
+  #
+  # === Change how we resolve the scope ===
+  # def resolve(scope)
+  #   ... code ...
+  # end
+  <%- end -%>
 end
 <% end -%>

data/lib/generators/jsonapi/templates/serializer.rb.erb

@@ -1,5 +1,22 @@
+<%- unless omit_comments? -%>
+# Serializers define the rendered JSON for a model instance.
+# We use jsonapi-rb, which is similar to active_model_serializers.
+<%- end -%>
 <% module_namespacing do -%>
 class Serializable<%= class_name %> < JSONAPI::Serializable::Resource
   type :<%= type %>
+
+  <%- unless omit_comments? -%>
+  # Add attributes here to ensure they get rendered, .e.g.
+  #
+  # attribute :name
+  #
+  # To customize, pass a block and reference the underlying @object
+  # being serialized:
+  #
+  # attribute :name do
+  #   @object.name.upcase
+  # end
+  <%- end -%>
 end
 <% end -%>

data/lib/jsonapi_compliable/adapters/active_record_sideloading.rb

@@ -47,7 +47,7 @@ module JsonapiCompliable
       def has_one(association_name, scope: nil, resource:, foreign_key:, primary_key: :id, &blk)
         _scope = scope
 
-        allow_sideload association_name, resource: resource do
+        allow_sideload association_name, type: :has_one, foreign_key: foreign_key, primary_key: primary_key, resource: resource do
           scope do |parents|
             parent_ids = parents.map { |p| p.send(primary_key) }
             _scope.call.where(foreign_key => parent_ids.uniq.compact)
@@ -71,7 +71,7 @@ module JsonapiCompliable
         fk      = foreign_key.values.first
         _scope  = scope
 
-        allow_sideload association_name, resource: resource do
+        allow_sideload association_name, type: :habtm, foreign_key: foreign_key, primary_key: primary_key, resource: resource do
           scope do |parents|
             parent_ids = parents.map { |p| p.send(primary_key) }
             parent_ids.uniq!
@@ -94,14 +94,14 @@ module JsonapiCompliable
       end
 
       def polymorphic_belongs_to(association_name, group_by:, groups:, &blk)
-        allow_sideload association_name, polymorphic: true do
-          group_by(&group_by)
+        allow_sideload association_name, type: :polymorphic_belongs_to, polymorphic: true do
+          group_by(group_by)
 
           groups.each_pair do |type, config|
             primary_key = config[:primary_key] || :id
             foreign_key = config[:foreign_key]
 
-            allow_sideload type, resource: config[:resource] do
+            allow_sideload type, parent: self, primary_key: primary_key, foreign_key: foreign_key, type: :belongs_to, resource: config[:resource] do
               scope do |parents|
                 parent_ids = parents.map { |p| p.send(foreign_key) }
                 parent_ids.compact!

data/lib/jsonapi_compliable/resource.rb

@@ -87,8 +87,6 @@ module JsonapiCompliable
   #     scope: -> { Comment.all },
   #     resource: CommentResource,
   #     foreign_key: :post_id
-  #
-  # @attr_reader [Hash] context A hash of +object+ and +namespace+ - Example object is a Rails controller, example namespace would be +:index+ or +:show+
   class Resource
     extend Forwardable
     attr_reader :context
@@ -451,16 +449,24 @@ module JsonapiCompliable
       end
     end
 
-    # The current context set by +#with_context+ in the form of
+    # The current context **object** set by +#with_context+. If you are
+    # using Rails, this is a controller instance.
     #
-    #   { object: context_obj, namespace: :index }
+    # This method is equivalent to +JsonapiCompliable.context[:object]+
     #
     # @see #with_context
-    # @return [Hash] the context hash
+    # @return the context object
     def context
       JsonapiCompliable.context[:object]
     end
 
+    # The current context **namespace** set by +#with_context+. If you
+    # are using Rails, this is the controller method name (e.g. +:index+)
+    #
+    # This method is equivalent to +JsonapiCompliable.context[:namespace]+
+    #
+    # @see #with_context
+    # @return [Symbol] the context namespace
     def context_namespace
       JsonapiCompliable.context[:namespace]
     end

data/lib/jsonapi_compliable/sideload.rb

@@ -6,7 +6,7 @@ module JsonapiCompliable
   # @attr_reader [Hash] sideloads The associated sibling sideloads
   # @attr_reader [Proc] scope_proc The configured 'scope' block
   # @attr_reader [Proc] assign_proc The configured 'assign' block
-  # @attr_reader [Proc] grouper The configured 'group_by' proc
+  # @attr_reader [Symbol] grouping_field The configured 'group_by' symbol
   # @attr_reader [Symbol] foreign_key The attribute used to match objects - need not be a true database foreign key.
   # @attr_reader [Symbol] primary_key The attribute used to match objects - need not be a true database primary key.
   # @attr_reader [Symbol] type One of :has_many, :belongs_to, etc
@@ -15,10 +15,11 @@ module JsonapiCompliable
       :resource_class,
       :polymorphic,
       :polymorphic_groups,
+      :parent,
       :sideloads,
       :scope_proc,
       :assign_proc,
-      :grouper,
+      :grouping_field,
       :foreign_key,
       :primary_key,
       :type
@@ -28,12 +29,13 @@ module JsonapiCompliable
     # An anonymous Resource will be assigned when none provided.
     #
     # @see Adapters::Abstract#sideloading_module
-    def initialize(name, type: nil, resource: nil, polymorphic: false, primary_key: :id, foreign_key: nil)
+    def initialize(name, type: nil, resource: nil, polymorphic: false, primary_key: :id, foreign_key: nil, parent: nil)
       @name               = name
       @resource_class     = (resource || Class.new(Resource))
       @sideloads          = {}
       @polymorphic        = !!polymorphic
       @polymorphic_groups = {} if polymorphic?
+      @parent             = parent
       @primary_key        = primary_key
       @foreign_key        = foreign_key
       @type               = type
@@ -55,7 +57,7 @@ module JsonapiCompliable
     # +Business+ or +Government+:
     #
     #   allow_sideload :organization, :polymorphic: true do
-    #     group_by { |record| record.organization_type }
+    #     group_by :organization_type
     #
     #     allow_sideload 'Business', resource: BusinessResource do
     #       # ... code ...
@@ -70,7 +72,7 @@ module JsonapiCompliable
     # with ActiveRecord:
     #
     #   polymorphic_belongs_to :organization,
-    #     group_by: ->(office) { office.organization_type },
+    #     group_by: :organization_type,
     #     groups: {
     #       'Business' => {
     #         scope: -> { Business.all },
@@ -181,21 +183,25 @@ module JsonapiCompliable
     # @see #name
     # @see #type
     def associate(parent, child)
-      resource_class.config[:adapter].associate(parent, child, name, type)
+      association_name = @parent ? @parent.name : name
+      resource_class.config[:adapter].associate parent,
+        child,
+        association_name,
+        type
     end
 
-    # Define a proc that groups the parent records. For instance, with
+    # Define an attribute that groups the parent records. For instance, with
     # an ActiveRecord polymorphic belongs_to there will be a +parent_id+
     # and +parent_type+. We would want to group on +parent_type+:
     #
     #  allow_sideload :organization, polymorphic: true do
     #    # group parent_type, parent here is 'organization'
-    #    group_by ->(office) { office.organization_type }
+    #    group_by :organization_type
     #  end
     #
     # @see #polymorphic?
-    def group_by(&grouper)
-      @grouper = grouper
+    def group_by(grouping_field)
+      @grouping_field = grouping_field
     end
 
     # Resolve the sideload.
@@ -323,6 +329,13 @@ module JsonapiCompliable
       result
     end
 
+    # @api private
+    def polymorphic_child_for_type(type)
+      polymorphic_groups.values.find do |v|
+        v.resource_class.config[:type] == type.to_sym
+      end
+    end
+
     private
 
     def nested_sideload_hash(sideload, processed)
@@ -333,8 +346,24 @@ module JsonapiCompliable
       end
     end
 
+    def polymorphic_grouper(grouping_field)
+      lambda do |record|
+        if record.is_a?(Hash)
+          if record.keys[0].is_a?(Symbol)
+            record[grouping_field]
+          else
+            record[grouping_field.to_s]
+          end
+        else
+          record.send(grouping_field)
+        end
+      end
+    end
+
     def resolve_polymorphic(parents, query)
-      parents.group_by(&@grouper).each_pair do |group_type, group_members|
+      grouper = polymorphic_grouper(@grouping_field)
+
+      parents.group_by(&grouper).each_pair do |group_type, group_members|
         sideload_for_group = @polymorphic_groups[group_type]
         if sideload_for_group
           sideload_for_group.resolve(group_members, query, name)