Move model parsing logic outside grape-swagger

Author: kzaitsev

.rubocop_todo.yml

@@ -23,12 +23,12 @@ Lint/UselessAssignment:
 
 # Offense count: 27
 Metrics/AbcSize:
-  Max: 68
+  Max: 69
 
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 234
+  Max: 284
 
 # Offense count: 11
 Metrics/CyclomaticComplexity:

CHANGELOG.md

@@ -7,6 +7,7 @@
 * [#405](https://github.com/ruby-grape/grape-swagger/pull/405), [#403](https://github.com/ruby-grape/grape-swagger/issues/403): Added version support matrix - [@LeFnord](https://github.com/LeFnord).
 * [#408](https://github.com/ruby-grape/grape-swagger/pull/408): Added support for `HEAD` endpoints - [@Bugagazavr](https://github.com/Bugagazavr).
 * [#408](https://github.com/ruby-grape/grape-swagger/pull/411): Added support for `OPTIONS` endpoints - [@Bugagazavr](https://github.com/Bugagazavr).
+* [#411](https://github.com/ruby-grape/grape-swagger/pull/413): Move all model parsing logic to separate gems `grape-swagger-entity` and added representable parser `grape-swagger` - [@Bugagazavr](https://github.com/Bugagazavr)
 * Your contribution here.
 
 #### Fixes

Gemfile

@@ -8,3 +8,5 @@ when 'HEAD'
 else
   gem 'grape', version
 end
+
+gem 'grape-swagger-entity', github: 'bugagazavr/grape-swagger-entity'

README.md

@@ -27,12 +27,24 @@ The grape-swagger gem provides an autogenerated documentation for your [Grape](h
 
 These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
 
+## Model Parsers
+
+Since 0.21.0, `Grape::Entity` is not a part of grape-swagger, you need to add `grape-swagger-entity` manually to your Gemfile:
+
+```ruby
+# For Grape::Entity ( https://github.com/ruby-grape/grape-entity )
+gem 'grape-swagger-entity'
+# For representable ( https://github.com/apotonick/representable )
+gem 'grape-swagger-representable'
+```
 
 <a name="related" />
 ## Related Projects
 
 * [Grape](https://github.com/ruby-grape/grape)
-* [Grape Entity](https://github.com/ruby-grape/grape-entity)
+* [Grape Swagger Entity](https://github.com/ruby-grape/grape-swagger-entity)
+  * [Grape Entity](https://github.com/ruby-grape/grape-entity)
+* [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
 * [Swagger UI](https://github.com/wordnik/swagger-ui)
 
 
@@ -46,7 +58,7 @@ grape-swagger | swagger spec | grape                   | grape-entity
 0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0
 0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0
 0.20.1        |     2.0      | >= 0.12.0 ... <= 0.14.0 | <= 0.5.1
-0.20.3 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1
+0.21.0 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1
 
 <a name="swagger-spec" />
 ## Swagger-Spec

grape-swagger.gemspec

@@ -12,9 +12,9 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
 
   s.add_runtime_dependency 'grape', '>= 0.12.0'
-  s.add_runtime_dependency 'grape-entity'
   s.add_runtime_dependency 'awesome_print'
 
+  s.add_development_dependency 'grape-entity'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'shoulda'
   s.add_development_dependency 'rdoc'

lib/grape-swagger.rb

@@ -7,12 +7,21 @@
 require 'grape-swagger/errors'
 
 require 'grape-swagger/doc_methods'
+require 'grape-swagger/model_parsers'
 
 require 'grape-swagger/markdown/kramdown_adapter'
 require 'grape-swagger/markdown/redcarpet_adapter'
 
 require 'awesome_print'
 
+module GrapeSwagger
+  class << self
+    def model_parsers
+      @model_parsers ||= GrapeSwagger::ModelParsers.new
+    end
+  end
+end
+
 module Grape
   class API
     class << self

lib/grape-swagger/endpoint.rb

@@ -226,55 +226,20 @@ def parse_request_params(required)
       end
     end
 
-    def parse_response_params(params)
-      return if params.nil?
-
-      params.each_with_object({}) do |x, memo|
-        next if x[1].fetch(:documentation, {}).fetch(:in, nil).to_s == 'header'
-        x[0] = x.last[:as] if x.last[:as]
-
-        model = x.last[:using] if x.last[:using].present?
-        model ||= x.last[:documentation][:type] if x.last[:documentation] && could_it_be_a_model?(x.last[:documentation])
-
-        if model
-          name = expose_params_from_model(model)
-          memo[x.first] = if x.last[:documentation] && x.last[:documentation][:is_array]
-                            { 'type' => 'array', 'items' => { '$ref' => "#/definitions/#{name}" } }
-                          else
-                            { '$ref' => "#/definitions/#{name}" }
-                          end
-        else
-          documented_type = x.last[:type]
-          documented_type ||= x.last[:documentation][:type] if x.last[:documentation]
-          data_type = GrapeSwagger::DocMethods::DataType.call(documented_type)
-
-          if GrapeSwagger::DocMethods::DataType.primitive?(data_type)
-            data = GrapeSwagger::DocMethods::DataType.mapping(data_type)
-            memo[x.first] = { type: data.first, format: data.last }
-          else
-            memo[x.first] = { type: data_type }
-          end
-
-          memo[x.first][:enum] = x.last[:values] if x.last[:values] && x.last[:values].is_a?(Array)
-        end
-        memo[x.first][:description] = x.last[:documentation][:desc] if x.last[:documentation] && x.last[:documentation][:desc]
-      end
-    end
-
     def expose_params_from_model(model)
       model_name = model_name(model)
 
-      # TODO: this should only be a temporary hack ;)
-      if GrapeEntity::VERSION =~ /0\.4\.\d/
-        parameters = model.exposures ? model.exposures : model.documentation
-      elsif GrapeEntity::VERSION =~ /0\.5\.\d/
-        parameters = model.root_exposures.each_with_object({}) do |value, memo|
-          memo[value.attribute] = value.send(:options)
-        end
+      properties = {}
+      GrapeSwagger.model_parsers.each do |klass, ancestor|
+        next unless model.ancestors.map(&:to_s).include?(ancestor)
+
+        model_class = klass.new(model, self)
+        properties = model_class.call
+
+        break
       end
-      properties = parse_response_params(parameters)
 
-      @definitions[model_name] = { type: 'object', properties: properties }
+      @definitions[model_name] = { type: 'object', properties: properties || {} }
 
       model_name
     end
@@ -283,17 +248,6 @@ def model_name(name)
       name.respond_to?(:name) ? name.name.demodulize.camelize : name.split('::').last
     end
 
-    def could_it_be_a_model?(value)
-      (
-        value[:type].to_s.include?('Entity') || value[:type].to_s.include?('Entities')
-      ) || (
-        value[:type] &&
-        value[:type].is_a?(Class) &&
-        !GrapeSwagger::DocMethods::DataType.primitive?(value[:type].name.downcase) &&
-        !value[:type] == Array
-      )
-    end
-
     def hidden?(route)
       route_hidden = route.options[:hidden]
       route_hidden = route_hidden.call if route_hidden.is_a?(Proc)

lib/grape-swagger/model_parsers.rb

@@ -0,0 +1,33 @@
+module GrapeSwagger
+  class ModelParsers
+    include Enumerable
+
+    def initialize
+      @parsers = {}
+    end
+
+    def register(klass, ancestor)
+      @parsers[klass] = ancestor.to_s
+    end
+
+    def insert_before(before_klass, klass, ancestor)
+      subhash = @parsers.except(klass).to_a
+      insert_at = subhash.index(subhash.assoc(before_klass))
+      insert_at = subhash.length - 1 if insert_at.nil?
+      @parsers = Hash[subhash.insert(insert_at, [klass, ancestor])]
+    end
+
+    def insert_after(after_klass, klass, ancestor)
+      subhash = @parsers.except(klass).to_a
+      insert_at = subhash.index(subhash.assoc(after_klass))
+      insert_at = subhash.length - 1 if insert_at.nil?
+      @parsers = Hash[subhash.insert(insert_at + 1, [klass, ancestor])]
+    end
+
+    def each
+      @parsers.each_pair do |klass, ancestor|
+        yield klass, ancestor
+      end
+    end
+  end
+end

spec/lib/model_parsers_spec.rb

@@ -0,0 +1,105 @@
+require 'spec_helper'
+
+describe GrapeSwagger::ModelParsers do
+  let(:model_parsers) { described_class.new }
+
+  before do
+    class SomeModelParser; end
+    class SomeModelParser2; end
+    class SomeModelParser3; end
+  end
+
+  describe '#register' do
+    describe 'successfully register new parser' do
+      before do
+        model_parsers.register(SomeModelParser, Class)
+      end
+
+      specify do
+        expect(model_parsers.to_a).to eq([[SomeModelParser, 'Class']])
+      end
+    end
+
+    describe 'should be empty if no registred parsers' do
+      specify do
+        expect(model_parsers.to_a).to be_empty
+      end
+    end
+  end
+
+  describe '#insert_before' do
+    describe 'SomeModelParser2 should be first parser' do
+      before do
+        model_parsers.register(SomeModelParser, Class)
+        model_parsers.register(SomeModelParser3, Class)
+        model_parsers.insert_before(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(3)
+        expect(model_parsers.to_a.first).to eq([SomeModelParser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if SomeModelParser not registred' do
+      before do
+        model_parsers.register(SomeModelParser3, Class)
+        model_parsers.insert_before(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(2)
+        expect(model_parsers.to_a).to include([SomeModelParser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if model parsers is empty' do
+      before do
+        model_parsers.insert_before(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(1)
+        expect(model_parsers.to_a).to include([SomeModelParser2, Class])
+      end
+    end
+  end
+
+  describe '#insert_after' do
+    describe 'SomeModelParser2 should be second parser' do
+      before do
+        model_parsers.register(SomeModelParser, Class)
+        model_parsers.register(SomeModelParser3, Class)
+        model_parsers.insert_after(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(3)
+        expect(model_parsers.to_a[1]).to eq([SomeModelParser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if SomeModelParser not registred' do
+      before do
+        model_parsers.register(SomeModelParser3, Class)
+        model_parsers.insert_after(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(2)
+        expect(model_parsers.to_a).to include([SomeModelParser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if model parsers is empty' do
+      before do
+        model_parsers.insert_after(SomeModelParser, SomeModelParser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(1)
+        expect(model_parsers.to_a).to include([SomeModelParser2, Class])
+      end
+    end
+  end
+end

spec/spec_helper.rb

@@ -3,8 +3,9 @@
 Dir[File.join(Dir.getwd, 'spec/support/**/*.rb')].each { |f| require f }
 
 require 'grape'
-require 'grape-swagger'
 require 'grape-entity'
+require 'grape-swagger'
+require 'grape-swagger/entity'
 
 Bundler.setup :default, :test