introspective_grape 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d2f679318dbf2d22e2af0c95708eee64adf103fb
-  data.tar.gz: 786a80ed73eec2168392904e459266dda8b22663
+  metadata.gz: 6af99e9a2be82ee669829ac17f9e84b767d74e12
+  data.tar.gz: eac78da439dd9c35844cbafd0cfd23428c3500de
 SHA512:
-  metadata.gz: 8ebf9eb5fd7859107a9d412cfe09728eb839191167b46cbd6d85ff9b1d740764cddc3acb621488c66e6b2d1a659f29c0b012c92948a35a478509e53012a5a5de
-  data.tar.gz: 9c8b93a2952bb15a2b8ba751efb1d49d00156a4267988068f91ce81ab71dad6860281b4d21c9d3424e6b162fd75fed26e835dbdf3e4d696d973e08700773ea1e
+  metadata.gz: 4531fc66b10fd1f3e84778572f7ba2c0e6d9a6c27f902ae6d13ebe55da68c6ab87ad6f19a6e37883678fc3bddcaeeab4f31cc790509c9ab9041249b36ac0aafd
+  data.tar.gz: 82660a9b2cd9683e78b4f2aacb11430e66a9a68a171f0ab3fdb4811613f264d4ebea20d51a9d0b27f3dbd7af5fa363ed3d2f76180755a8abb07246a30759111c

data/CHANGELOG.md

@@ -1,4 +1,20 @@
 
+0.2.2 10/20/2016
+==============
+
+### Bug Fix
+
+The default pagination values for Kaminari in snake case were overwriting the passed values
+in camel case, update the camel_snake_keys dependency so key conflicts resolve in favor of
+the expected convention.
+
+0.2.1 10/20/2016
+==============
+
+Require explicit declarations for index filters using `filter_on :attribute`. Automatically generate filters on all fields as before using `filter_on :all`.
+
+Defer endpoint documentation to <action>_documentation class methods on the API, so docs can be written.
+
 0.2.0 10/12/2016
 ==============
 

data/README.md

@@ -125,18 +125,27 @@ creating bulk update endpoints for nested models.
 
 ## Filtering and Searching
 
-IntrospectiveGrape will automatically generate and parse filters on all exposed fields in the API.
+Simple filters on field values (and start and end values for timestamps) can be added with the `filter_on` declaration. Declaring `filter_on :all` will add filters for every attribute of the model.
+
+```
+class MyModelAPI < IntrospectiveGrape::API
+  filter_on :my_attribute, :my_other_attribute
+end
+```
 
 Multiple values can be specified at once for Integer attributes that end in "id" (i.e. conventional primary and foreign keys) at once by passing a comma separated list of IDs.
 
 For timestamp attributes it will generate `<name_of_timestamp>_start` and `<name_of_timestamp>_end` constraints.
 
+There is also a special "filter" filter, that allows a JSON hash to be passed of attributes and values: this allows more complex filtering if one is familiar with ActiveRecord's query conventions.
+
 ### Overriding Filter Queries
 
 If, e.g., a field is some sort of complex composite rather than a simple field value you can override the default behavior (`where(field: params[field])`) by adding a query method on the model class:
 
 ```
 class MyAPI < IntrospectiveGrape::API
+  filter_on :my_composite_field
   restful MyModel, [my_composite_field]
 end
 
@@ -169,6 +178,9 @@ class MyModel
 end
 ```
 
+## Documenting Endpoints
+
+If you wish to provide additional documentation for end points you can define `<action>_documentation` methods in the API class.
 
 ## Pagination
 

data/introspective_grape.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'grape-swagger',  '~>0.11.0'
   s.add_dependency 'grape-kaminari', '~>0.1.9'
   s.add_dependency 'pundit'
-  s.add_dependency 'camel_snake_keys', '~>0.0.2'
+  s.add_dependency 'camel_snake_keys', '~>0.0.4'
 
   if RUBY_PLATFORM == 'java'
     #s.add_development_dependency "jdbc-sqlite3"

data/lib/introspective_grape/api.rb

@@ -6,6 +6,7 @@ module IntrospectiveGrape
     extend IntrospectiveGrape::Helpers
     extend IntrospectiveGrape::Filters
     extend IntrospectiveGrape::Traversal
+    extend IntrospectiveGrape::Doc
 
     # Allow files to be uploaded through ActionController:
     ActionController::Parameters::PERMITTED_SCALAR_TYPES.push Rack::Multipart::UploadedFile, ActionController::Parameters
@@ -154,7 +155,7 @@ module IntrospectiveGrape
         simple_filters(klass, model, api_params)
 
         dsl.desc "list #{name}" do
-          detail "returns list of all #{name}"
+          detail klass.index_documentation || "returns list of all #{name}"
         end
         dsl.params do
           klass.declare_filter_params(self, klass, model, api_params)
@@ -182,7 +183,7 @@ module IntrospectiveGrape
         name = routes.last.name.singularize
         klass = routes.first.klass
         dsl.desc "retrieve a #{name}" do
-          detail "returns details on a #{name}"
+          detail klass.show_documentation || "returns details on a #{name}"
         end
         dsl.get ":#{routes.last.swaggerKey}" do
           authorize @model, :show?
@@ -195,7 +196,7 @@ module IntrospectiveGrape
         klass = routes.first.klass
         root  = routes.first
         dsl.desc "create a #{name}" do
-          detail "creates a new #{name} record"
+          detail klass.create_documentation || "creates a new #{name} record"
         end
         dsl.params do
           klass.generate_params(self, klass, :create, model, api_params)
@@ -216,7 +217,7 @@ module IntrospectiveGrape
         klass = routes.first.klass
         name = routes.last.name.singularize
         dsl.desc "update a #{name}" do
-          detail "updates the details of a #{name}"
+          detail klass.update_documentation || "updates the details of a #{name}"
         end
         dsl.params do
           klass.generate_params(self, klass, :update, model, api_params)
@@ -234,7 +235,7 @@ module IntrospectiveGrape
         klass = routes.first.klass
         name = routes.last.name.singularize
         dsl.desc "destroy a #{name}" do
-          detail "destroys the details of a #{name}"
+          detail klass.destroy_documentation || "destroys the details of a #{name}"
         end
         dsl.delete ":#{routes.last.swaggerKey}" do
           authorize @model, :destroy?

data/lib/introspective_grape/doc.rb

@@ -0,0 +1,9 @@
+module IntrospectiveGrape
+  module Doc
+    def index_documentation; end
+    def show_documentation; end
+    def create_documentation; end
+    def update_documentation; end
+    def destroy_documentation; end
+  end
+end

data/lib/introspective_grape/filters.rb

@@ -14,8 +14,20 @@ module IntrospectiveGrape::Filters
     @custom_filters
   end
 
+  def filter_on(*args)
+    filters( *args )
+  end
+
+  def filters(*args)
+    @filters ||= []
+    @filters   = @filters+args if args.present?
+    @filters
+  end
+
   def simple_filters(klass, model, api_params)
-    @simple_filters ||= api_params.select {|p| p.is_a? Symbol }.map { |field|
+    @simple_filters ||= api_params.select {|p| p.is_a? Symbol }.select {|field| 
+      filters.include?(:all) || filters.include?(field)
+    }.map { |field|
       (klass.param_type(model,field) == DateTime ? ["#{field}_start", "#{field}_end"] : field.to_s)
     }.flatten
   end
@@ -55,7 +67,7 @@ module IntrospectiveGrape::Filters
       dsl.optional filter, details
     end
 
-    dsl.optional :filter, type: String, description: "JSON of conditions for query. If you're familiar with ActiveRecord's query conventions you can build more complex filters, e.g. against included child associations, e.g. {\"<association_name>_<parent>\":{\"field\":\"value\"}}"
+    dsl.optional :filter, type: String, description: "JSON of conditions for query. If you're familiar with ActiveRecord's query conventions you can build more complex filters, e.g. against included child associations, e.g. {\"&lt;association_name&gt;_&lt;parent&gt;\":{\"field\":\"value\"}}" if filters.include?(:all) || filters.include?(:filter)
 
   end
 

data/lib/introspective_grape/version.rb

@@ -1,3 +1,3 @@
 module IntrospectiveGrape
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.2".freeze
 end

data/lib/introspective_grape.rb

@@ -1,6 +1,7 @@
 module IntrospectiveGrape
   autoload :API,        'introspective_grape/api'
   autoload :CamelSnake, 'introspective_grape/camel_snake'
+  autoload :Doc,        'introspective_grape/doc'
   autoload :Filters,    'introspective_grape/filters'
   autoload :Helpers,    'introspective_grape/helpers'
   autoload :Traversal,  'introspective_grape/traversal'

data/spec/dummy/app/api/dummy/location_api.rb

@@ -5,6 +5,8 @@ class Dummy::LocationAPI < IntrospectiveGrape::API
 
   default_includes Location, :child_locations, :gps, :beacons, :locatables
 
+  filter_on :name, :filter
+
   restful Location, [:name, :kind,
     {gps_attributes: [:id, :lat, :lng, :alt, :_destroy]},
     {beacons_attributes: [:id, :company_id, :mac_address, :uuid, :major, :minor, :_destroy]},

data/spec/dummy/app/api/dummy/user_api.rb

@@ -6,6 +6,8 @@ class Dummy::UserAPI < IntrospectiveGrape::API
   exclude_actions Role, :show,:update
   exclude_actions UserProjectJob, :show,:update
 
+  filter_on :all
+
   restful User, [:id, :email, :password, :first_name, :last_name, :skip_confirmation_email,
     :created_at, :updated_at,
     user_project_jobs_attributes: [:id, :job_id, :project_id, :_destroy],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: introspective_grape
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Josh Buermann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-18 00:00:00.000000000 Z
+date: 2016-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -106,14 +106,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.4
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -271,6 +271,7 @@ files:
 - lib/introspective_grape.rb
 - lib/introspective_grape/api.rb
 - lib/introspective_grape/camel_snake.rb
+- lib/introspective_grape/doc.rb
 - lib/introspective_grape/filters.rb
 - lib/introspective_grape/formatter/camel_json.rb
 - lib/introspective_grape/helpers.rb