Merge pull request ruby-grape#413 from Bugagazavr/representers

Representers

Author: dblock

.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:

.travis.yml

@@ -4,6 +4,10 @@ sudo: false
 
 matrix:
   include:
+    - rvm: 2.3.1
+      env: MODEL_PARSER=grape-swagger-entity
+    - rvm: 2.3.1
+      env: MODEL_PARSER=grape-swagger-representable
     - rvm: 2.3.1
       env: GRAPE_VERSION=0.12.0
     - rvm: 2.3.1

CHANGELOG.md

@@ -1,5 +1,8 @@
 ### Next
 
+#### Features
+
+* [#413](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.
 
 ### 0.20.3 (May 9, 2016)

Gemfile

@@ -8,3 +8,5 @@ when 'HEAD'
 else
   gem 'grape', version
 end
+
+gem ENV['MODEL_PARSER'], github: "bugagazavr/#{ENV['MODEL_PARSER']}" if ENV.key?('MODEL_PARSER')

README.md

@@ -27,12 +27,71 @@ 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.
+Also added support for [representable](https://github.com/apotonick/representable) via `grape-swagger-representable`.
+
+```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'
+```
+
+##### Custom Model Parsers
+
+You can create your own model parser, for example for [roar](https://github.com/apotonick/roar).
+
+```rb
+module GrapeSwagger
+  module Roar
+    class Parser
+      attr_reader :model
+      attr_reader :endpoint
+
+      def initialize(model, endpoint)
+        @model = model
+        @endpoint = endpoint
+      end
+
+      def call
+        # Parse your model and return hash with model schema for swagger
+      end
+    end
+  end
+end
+```
+
+Then you should register your custom parser.
+
+```rb
+GrapeSwagger.model_parsers.register(GrapeSwagger::Roar::Parser, Roar::Decorator)
+```
+
+To control model parsers sequence, you can insert your parser before or after another parser.
+
+#### insert_before
+
+```rb
+GrapeSwagger.model_parsers.insert_before(GrapeSwagger::Representable::Parser, GrapeSwagger::Roar::Parser, Roar::Decorator)
+```
+
+#### insert_after
+
+```rb
+GrapeSwagger.model_parsers.insert_after(GrapeSwagger::Roar::Parser, GrapeSwagger::Representable::Parser, Representable::Decorator)
+```
+
+As we know, `Roar::Decorator` uses as superclass `Representable::Decorator`, this allow to avoid problem when Roar objects will be processed by `GrapeSwagger::Representable::Parser`, instead `GrapeSwagger::Roar::Parser`.
 
 <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)
 
 
@@ -41,12 +100,13 @@ These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) s
 
 The following versions of grape, grape-entity and grape-swagger can currently be used together.
 
-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        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1
+grape-swagger | swagger spec | grape                   | grape-entity | representable |
+--------------|--------------|-------------------------|--------------|---------------|
+0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0     | n/a           |
+0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0     | n/a           |
+0.20.1        |     2.0      | >= 0.12.0 ... <= 0.14.0 | <= 0.5.1     | n/a           |
+0.20.3        |     2.0      | >= 0.12.0 ... ~> 0.16.2 | ~> 0.5.1     | n/a           |
+0.21.0 (next) |     2.0      | >= 0.12.0 ... <= 0.16.2 | <= 0.5.1     | >= 2.4.1      |
 
 <a name="swagger-spec" />
 ## Swagger-Spec

UPGRADING.md

@@ -1,6 +1,15 @@
 Upgrading Grape-swagger
 =======================
 
+### Upgrading to >= 0.21.0
+
+With grape >= 0.21.0, `grape-entity` support moved to separate gem `grape-swagger-entity`, if you use grape entity, update your Gemfile:
+
+```ruby
+gem 'grape-swagger'
+gem 'grape-swagger-entity'
+```
+
 ### Upgrading to >= 0.10.2
 
 With grape >= 0.12.0, support for `notes` is replaced by passing a block `detail` option specified. For future compatibility, update your code:

grape-swagger.gemspec

@@ -12,7 +12,6 @@ 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 'rake'

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,102 @@
+require 'spec_helper'
+
+describe GrapeSwagger::ModelParsers do
+  let(:model_parsers) { described_class.new }
+  let(:parser) { Class.new }
+  let(:parser2) { Class.new }
+  let(:parser3) { Class.new }
+
+  describe '#register' do
+    describe 'successfully register new parser' do
+      before do
+        model_parsers.register(parser, Class)
+      end
+
+      specify do
+        expect(model_parsers.to_a).to eq([[parser, '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(parser, Class)
+        model_parsers.register(parser3, Class)
+        model_parsers.insert_before(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(3)
+        expect(model_parsers.to_a.first).to eq([parser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if SomeModelParser not registred' do
+      before do
+        model_parsers.register(parser3, Class)
+        model_parsers.insert_before(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(2)
+        expect(model_parsers.to_a).to include([parser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if model parsers is empty' do
+      before do
+        model_parsers.insert_before(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(1)
+        expect(model_parsers.to_a).to include([parser2, Class])
+      end
+    end
+  end
+
+  describe '#insert_after' do
+    describe 'SomeModelParser2 should be second parser' do
+      before do
+        model_parsers.register(parser, Class)
+        model_parsers.register(parser3, Class)
+        model_parsers.insert_after(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(3)
+        expect(model_parsers.to_a[1]).to eq([parser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if SomeModelParser not registred' do
+      before do
+        model_parsers.register(parser3, Class)
+        model_parsers.insert_after(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(2)
+        expect(model_parsers.to_a).to include([parser2, Class])
+      end
+    end
+
+    describe 'SomeModelParser2 should be inserted anyway if model parsers is empty' do
+      before do
+        model_parsers.insert_after(parser, parser2, Class)
+      end
+
+      specify do
+        expect(model_parsers.count).to eq(1)
+        expect(model_parsers.to_a).to include([parser2, Class])
+      end
+    end
+  end
+end