grape-swagger 0.11.0 → 0.20.0

data/RELEASING.md

@@ -1,17 +1,16 @@
 # Releasing Grape-Swagger
 
-There're no particular rules about when to release grape-swagger. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+There're no particular rules about when to release grape-swagger. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
 
 ### Release
 
-Run tests and rubocop, check that all tests succeed locally.
+Run tests, check that all tests succeed locally.
 
 ```
 bundle install
-bundle exec rake
+rake
 ```
 
-
 Check that the last build succeeded in [Travis CI](https://travis-ci.org/ruby-grape/grape-swagger) for all supported platforms.
 
 Increment the version, modify [lib/grape-swagger/version.rb](lib/grape-swagger/version.rb).

data/example/api/endpoints.rb

@@ -0,0 +1,132 @@
+require 'grape-entity'
+require './api/entities'
+
+module Api
+  class Spline
+    attr_accessor :id, :x, :y, :reticulated
+  end
+
+  module Endpoints
+    class Root < Grape::API
+      desc 'API Root'
+      get do
+        {
+          splines_url: '/splines',
+          file_url: '/file'
+        }
+      end
+    end
+
+    class Splines < Grape::API
+
+      @@splines = []
+
+      namespace :splines do
+        #
+        desc 'Get all splines',
+          is_array: true,
+          http_codes: [
+            { code: 200, message: 'get Splines', model: Api::Entities::Splines },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        get do
+          present :items, @@splines, with: Entities::Splines
+        end
+
+        #
+        desc 'Return a spline.',
+          http_codes: [
+            { code: 200, message: 'get Splines' },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+        end
+        get ':id' do
+          error!({ code: 422, message: 'SplinesOutError' }) unless @@splines[params[:id] - 1]
+
+          present @@splines[params[:id] - 1], with: Entities::Splines
+        end
+
+        #
+        desc 'Create a spline.',
+          http_codes: [
+            { code: 201, message: 'Spline created', model: Api::Entities::Splines }
+          ]
+        params do
+          requires :spline, type: Hash do
+            requires :x, type: Numeric
+            requires :y, type: Numeric
+          end
+          optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+        end
+        post do
+          spline = Spline.new
+          spline.id =  @@splines.size + 1
+          spline.x =  (params[:spline][:x]/params[:spline][:y] || 0.0)
+          spline.y =  (params[:spline][:y]/params[:spline][:x] || 0.0)
+          spline.reticulated =  params[:reticulated]
+
+          @@splines << spline
+
+          present spline, with: Entities::Splines
+        end
+
+        #
+        desc 'Update a spline.',
+          http_codes: [
+            { code: 200, message: 'update Splines', model: Api::Entities::Splines },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+          optional :spline, type: Hash do
+            optional :x, type: Numeric
+            optional :y, type: Numeric
+          end
+          optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+        end
+        put ':id' do
+          error!({ code: 422, message: 'SplinesOutError' }) unless @@splines[params[:id] - 1]
+
+          update_data = params[:spline]
+          spline      = @@splines[params[:id] - 1]
+
+          spline.reticulated = !!update_data[:reticulated]
+          spline.x           = update_data[:x]/update_data[:y] || 0.0
+          spline.y           = update_data[:y]/update_data[:x] || 0.0
+
+          present spline, with: Entities::Splines
+        end
+
+        #
+        desc 'Delete a spline.'
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+        end
+        delete ':id' do
+          error!({ code: 422, message: 'SplinesOutError' }) unless @@splines[params[:id] - 1]
+
+          @@splines.delete_at(params[:id] - 1)
+          { "deleted": params[:id] }
+        end
+      end
+    end
+
+    class FileAccessor < Grape::API
+      namespace :file do
+        desc 'Update image',
+          details: "# TEST api for testing uploading\n
+                    # curl --form file=@splines.png http://localhost:9292/file/upload",
+          content_type: 'application/octet-stream'
+        post 'upload' do
+          filename = params[:file][:filename]
+          content_type 'binary', 'application/octet-stream'
+          # env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
+          header 'Content-Disposition', "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+          params[:file][:tempfile].read
+        end
+      end
+    end
+  end
+end

data/example/api/entities.rb

@@ -0,0 +1,18 @@
+require 'grape-entity'
+
+module Api
+  module Entities
+    class Splines < Grape::Entity
+      expose :id, documentation: { type: Integer, desc: 'identity of a resource' }
+      expose :x, documentation: { type: Float, desc: 'x-value' }
+      expose :y, documentation: { type: Float, desc: 'y-value' }
+      expose :path, documentation: { type: String, desc: 'the requested resource'}
+
+      private
+
+      def path
+        "/#{object.class.name.demodulize.to_s.underscore}/#{object.id}"
+      end
+    end
+  end
+end

data/example/config.ru

@@ -6,5 +6,39 @@ use Rack::Cors do
   end
 end
 
-require './api'
-run Api.new
+require 'grape'
+
+require './api/endpoints'
+require './api/entities'
+
+class Base < Grape::API
+  require 'grape-entity'
+  require '../lib/grape-swagger'
+  format :json
+
+  mount Api::Endpoints::Root
+  mount Api::Endpoints::Splines
+  mount Api::Endpoints::FileAccessor
+
+  before do
+    header['Access-Control-Allow-Origin'] = '*'
+    header['Access-Control-Request-Method'] = '*'
+  end
+
+  # global exception handler, used for error notifications
+  rescue_from :all do |e|
+    raise e
+    error_response(message: "Internal server error: #{e}", status: 500)
+  end
+
+  add_swagger_documentation :hide_documentation_path => true,
+                            :api_version => 'v1',
+                            :info => {
+                              title: "Horses and Hussars",
+                              description: "Demo app for dev of grape swagger 2.0"
+                            }
+
+end
+
+
+run Base.new

data/example/example_requests.postman_collection

@@ -0,0 +1,146 @@
+{
+	"id": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+	"name": "grape-rackup",
+	"description": "",
+	"order": [
+		"cf633582-c2ea-cb44-24d7-d64e73a65049",
+		"60bd637b-7b77-b280-d4f7-3d3d38cd86ef",
+		"4780e2ef-f05d-f464-9d18-538c5960be3c",
+		"f83c2241-c239-13ea-bffb-255436e95863",
+		"0648649b-9e54-1bc5-f835-2c690f67d47a"
+	],
+	"folders": [],
+	"timestamp": 1453407636651,
+	"owner": "",
+	"remoteLink": "",
+	"public": false,
+	"requests": [
+		{
+			"id": "0648649b-9e54-1bc5-f835-2c690f67d47a",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"preRequestScript": "",
+			"pathVariables": {},
+			"method": "DELETE",
+			"data": [],
+			"dataMode": "params",
+			"version": 2,
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"time": 1453408596777,
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"responses": []
+		},
+		{
+			"id": "4780e2ef-f05d-f464-9d18-538c5960be3c",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "GET",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [
+				{
+					"key": "required_group[required_param_1]",
+					"value": "sadf",
+					"type": "text",
+					"enabled": true
+				},
+				{
+					"key": "required_group[required_param_2]",
+					"value": "fgsd",
+					"type": "text",
+					"enabled": true
+				}
+			],
+			"dataMode": "params",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408415061,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {}
+		},
+		{
+			"id": "60bd637b-7b77-b280-d4f7-3d3d38cd86ef",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "GET",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [
+				{
+					"key": "required_group[required_param_1]",
+					"value": "sadf",
+					"type": "text",
+					"enabled": true
+				},
+				{
+					"key": "required_group[required_param_2]",
+					"value": "fgsd",
+					"type": "text",
+					"enabled": true
+				}
+			],
+			"dataMode": "params",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408387712,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {}
+		},
+		{
+			"id": "cf633582-c2ea-cb44-24d7-d64e73a65049",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "POST",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [],
+			"dataMode": "raw",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453407769825,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"rawModeData": "{\n    \"spline\":{\n        \"x\":1.23,\n        \"y\":3.14\n    }\n}"
+		},
+		{
+			"id": "f83c2241-c239-13ea-bffb-255436e95863",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "PUT",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [],
+			"dataMode": "raw",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408494448,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"rawModeData": "{\n    \"spline\":{\n        \"x\":131.23,\n        \"y\":93.14\n    }\n}"
+		}
+	]
+}

data/grape-swagger.gemspec

@@ -11,8 +11,9 @@ Gem::Specification.new do |s|
   s.summary     = 'A simple way to add auto generated documentation to your Grape API that can be displayed with Swagger.'
   s.license     = 'MIT'
 
-  s.add_runtime_dependency 'grape', '>= 0.16.2'
-  s.add_runtime_dependency 'grape-entity', '< 0.5.0'
+  s.add_runtime_dependency 'grape'
+  s.add_runtime_dependency 'grape-entity'
+  s.add_runtime_dependency 'awesome_print'
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'shoulda'
@@ -21,10 +22,12 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'rack-test'
   s.add_development_dependency 'rack-cors'
-  s.add_development_dependency 'rubocop', '0.33.0'
-  s.add_development_dependency 'kramdown', '~> 1.4.1'
-  s.add_development_dependency 'redcarpet', '~> 3.1.2' unless RUBY_PLATFORM.eql? 'java'
-  s.add_development_dependency 'rouge', '~> 1.6.1'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'kramdown'
+  s.add_development_dependency 'redcarpet' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
+  s.add_development_dependency 'rouge' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
+  s.add_development_dependency 'pry' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
+  s.add_development_dependency 'pry-byebug' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")

data/lib/grape-swagger.rb

@@ -1,20 +1,24 @@
 require 'grape'
 require 'grape-swagger/version'
+require 'grape-swagger/endpoint'
 require 'grape-swagger/errors'
+
 require 'grape-swagger/doc_methods'
-require 'grape-swagger/markdown'
+
 require 'grape-swagger/markdown/kramdown_adapter'
 require 'grape-swagger/markdown/redcarpet_adapter'
 
+require 'awesome_print'
+
 module Grape
   class API
     class << self
       attr_accessor :combined_routes, :combined_namespaces, :combined_namespace_routes, :combined_namespace_identifiers
-      attr_accessor :endpoint_mapping
 
       def add_swagger_documentation(options = {})
         documentation_class = create_documentation_class
 
+        version_for(options)
         options = { target_class: self }.merge(options)
         @target_class = options[:target_class]
 
@@ -22,20 +26,8 @@ module Grape
         mount(documentation_class)
 
         @target_class.combined_routes = {}
-        @target_class.routes.each do |route|
-          route_path = route.path
-          route_match = route_path.split(/^.*?#{route.prefix.to_s}/).last
-          next unless route_match
-          route_match = route_match.match('\/([\w|-]*?)[\.\/\(]') || route_match.match('\/([\w|-]*)$')
-          next unless route_match
-          resource = route_match.captures.first
-          next if resource.empty?
-          @target_class.combined_routes[resource] ||= []
-          next if documentation_class.hide_documentation_path && route.path.match(/#{documentation_class.mount_path}($|\/|\(\.)/)
-          @target_class.combined_routes[resource] << route
-        end
+        combine_routes(@target_class, documentation_class)
 
-        @target_class.endpoint_mapping = {}
         @target_class.combined_namespaces = {}
         combine_namespaces(@target_class)
 
@@ -50,6 +42,26 @@ module Grape
 
       private
 
+      def version_for(options)
+        options[:version] = version if version
+      end
+
+      def combine_routes(app, doc_klass)
+        app.routes.each do |route|
+          route_path = route.route_path
+          route_match = route_path.split(/^.*?#{route.route_prefix.to_s}/).last
+          next unless route_match
+          route_match = route_match.match('\/([\w|-]*?)[\.\/\(]') || route_match.match('\/([\w|-]*)$')
+          next unless route_match
+          resource = route_match.captures.first
+          next if resource.empty?
+          resource.downcase!
+          @target_class.combined_routes[resource] ||= []
+          next if doc_klass.hide_documentation_path && route.route_path.match(/#{doc_klass.mount_path}($|\/|\(\.)/)
+          @target_class.combined_routes[resource] << route
+        end
+      end
+
       def combine_namespaces(app)
         app.endpoints.each do |endpoint|
           ns = if endpoint.respond_to?(:namespace_stackable)
@@ -61,10 +73,6 @@ module Grape
           # and strip leading slash
           @target_class.combined_namespaces[endpoint.namespace.sub(/^\//, '')] = ns if ns
 
-          endpoint.routes.each do |route|
-            @target_class.endpoint_mapping[route.to_s.sub('(.:format)', '')] = endpoint
-          end
-
           combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
         end
       end
@@ -76,35 +84,32 @@ module Grape
           parent_route_name = name.match(%r{^/?([^/]*).*$})[1]
           parent_route = @target_class.combined_routes[parent_route_name]
           # fetch all routes that are within the current namespace
-          namespace_routes = parent_route.collect do |route|
-            route if (route.path.start_with?(route.prefix ? "/#{route.prefix}/#{name}" : "/#{name}") || route.path.start_with?((route.prefix ? "/#{route.prefix}/:version/#{name}" : "/:version/#{name}"))) &&
-                     (route.instance_variable_get(:@options)[:namespace] == "/#{name}" || route.instance_variable_get(:@options)[:namespace] == "/:version/#{name}")
-          end.compact
+          namespace_routes = parent_route.reject do |route|
+            !route_path_start_with?(route, name) || !route_instance_variable_equals?(route, name)
+          end
 
           if namespace.options.key?(:swagger) && namespace.options[:swagger][:nested] == false
             # Namespace shall appear as standalone resource, use specified name or use normalized path as name
-            identifier = if namespace.options[:swagger].key?(:name)
-                           namespace.options[:swagger][:name].tr(' ', '-')
-                         else
-                           name.tr('_', '-').gsub(/\//, '_')
-                         end
+            identifier =  if namespace.options[:swagger].key?(:name)
+                            name.tr(' ', '-')
+                          else
+                            name.tr('_', '-').gsub(/\//, '_')
+                          end
             @target_class.combined_namespace_identifiers[identifier] = name
             @target_class.combined_namespace_routes[identifier] = namespace_routes
 
-            # get all nested namespaces below the current namespace
+            # # get all nested namespaces below the current namespace
             sub_namespaces = standalone_sub_namespaces(name, namespaces)
-            # convert namespace to route names
-            sub_ns_paths = sub_namespaces.collect { |ns_name, _| "/#{ns_name}" }
-            sub_ns_paths_versioned = sub_namespaces.collect { |ns_name, _| "/:version/#{ns_name}" }
-            # get the actual route definitions for the namespace path names
-            sub_routes = parent_route.collect do |route|
-              route if sub_ns_paths.include?(route.instance_variable_get(:@options)[:namespace]) || sub_ns_paths_versioned.include?(route.instance_variable_get(:@options)[:namespace])
-            end.compact
-            # add all determined routes of the sub namespaces to standalone resource
+            sub_routes = sub_routes_from(parent_route, sub_namespaces)
             @target_class.combined_namespace_routes[identifier].push(*sub_routes)
           else
             # default case when not explicitly specified or nested == true
-            standalone_namespaces = namespaces.reject { |_, ns| !ns.options.key?(:swagger) || !ns.options[:swagger].key?(:nested) || ns.options[:swagger][:nested] != false }
+            standalone_namespaces = namespaces.reject do |_, ns|
+              !ns.options.key?(:swagger) ||
+                !ns.options[:swagger].key?(:nested) ||
+                ns.options[:swagger][:nested] != false
+            end
+
             parent_standalone_namespaces = standalone_namespaces.reject { |ns_name, _| !name.start_with?(ns_name) }
             # add only to the main route if the namespace is not within any other namespace appearing as standalone resource
             if parent_standalone_namespaces.empty?
@@ -116,6 +121,32 @@ module Grape
         end
       end
 
+      def sub_routes_from(parent_route, sub_namespaces)
+        sub_ns_paths = sub_namespaces.collect { |ns_name, _| ["/#{ns_name}", "/:version/#{ns_name}"] }
+        sub_routes = parent_route.reject do |route|
+          parent_namespace = route_instance_variable(route)
+          !sub_ns_paths.assoc(parent_namespace) && !sub_ns_paths.rassoc(parent_namespace)
+        end
+
+        sub_routes
+      end
+
+      def route_instance_variable(route)
+        route.instance_variable_get(:@options)[:namespace]
+      end
+
+      def route_instance_variable_equals?(route, name)
+        route_instance_variable(route) == "/#{name}" ||
+          route_instance_variable(route) == "/:version/#{name}"
+      end
+
+      def route_path_start_with?(route, name)
+        route_prefix = route.route_prefix ? "/#{route.route_prefix}/#{name}" : "/#{name}"
+        route_versioned_prefix = route.route_prefix ? "/#{route.route_prefix}/:version/#{name}" : "/:version/#{name}"
+
+        route.route_path.start_with?(route_prefix, route_versioned_prefix)
+      end
+
       def standalone_sub_namespaces(name, namespaces)
         # assign all nested namespace routes to this resource, too
         # (unless they are assigned to another standalone namespace themselves)
@@ -132,67 +163,6 @@ module Grape
         sub_namespaces
       end
 
-      def get_non_nested_params(params)
-        # Duplicate the params as we are going to modify them
-        dup_params = params.each_with_object({}) do |(param, value), dparams|
-          dparams[param] = value.dup
-        end
-
-        dup_params.reject do |param, value|
-          is_nested_param = /^#{ Regexp.quote param }\[.+\]$/
-          0 < dup_params.count do |p, _|
-            match = p.match(is_nested_param)
-            dup_params[p][:required] = false if match && !value[:required]
-            match
-          end
-        end
-      end
-
-      def parse_array_params(params)
-        modified_params = {}
-        array_keys = []
-        params.each_key do |k|
-          new_key, modified_params = parse_array_key(array_keys, k, modified_params)
-          if params[k].is_a?(Hash) && params[k][:type] == 'Array'
-            array_keys.push(new_key)
-          end
-          modified_params[new_key] = params[k]
-        end
-        modified_params
-      end
-
-      def parse_array_key(array_keys, key, modified_params)
-        unless array_keys.blank?
-          array_keys.each do |array_key|
-            if key.to_s.start_with?(array_key.to_s + '[')
-              key = array_key.to_s + '[]' + key.to_s.split(array_key)[1]
-              modified_params.delete array_key
-            end
-          end
-        end
-        [key, modified_params]
-      end
-
-      def parse_enum_or_range_values(values)
-        case values
-        when Range
-          parse_range_values(values) if values.first.is_a?(Integer)
-        when Proc
-          values_result = values.call
-          if values_result.is_a?(Range) && values_result.first.is_a?(Integer)
-            parse_range_values(values_result)
-          else
-            { enum: values_result }
-          end
-        else
-          { enum: values } if values
-        end
-      end
-
-      def parse_range_values(values)
-        { minimum: values.first, maximum: values.last }
-      end
-
       def create_documentation_class
         Class.new(Grape::API) do
           extend GrapeSwagger::DocMethods