grape-swagger 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9e2d67cf94749b685aff4146aa6f831acd41539
-  data.tar.gz: 272fa686ecf0e978a0f07c41a42486a06ecfd56c
+  metadata.gz: 80476f6e354bf1964123a1f592e8a6ca9fd38d54
+  data.tar.gz: b9c15ab8ac8cacbd87e69e187a1afd2a838ff7d7
 SHA512:
-  metadata.gz: 612b8bff2f52780da77e09b63a929cb035d3cc6f8bcda1a75b426c7267c67e60f86d30eefa149e05f6ec27571317cef910daf53026b7d3394d149ccafb96ce07
-  data.tar.gz: 22b1bd381a910aedb712fa1efc53b36ded5965ae743dae44527f49208cc23243d8d97f3ff76694d984f06e2ede024d5d2b01feda3356c436a5890a44b3e06930
+  metadata.gz: 4f6d6e3da7140010e92a6a94a716572cf2da3093bc2233c172c6a9d0caa420a4108da068d73a145ae901dd61cc2c754c22974881cab22a5959fb55439fdfaeb1
+  data.tar.gz: 04db505e755cf5fa4f72684becaa3ad2a580a1f83baf566fb8c7407f2c1b425f809d813b1151c7b286f0f4ed90e587307be53c15f3ab9ef90b579af4d5c8d803

data/.rubocop_todo.yml

@@ -1,42 +1,42 @@
 # This configuration was generated by `rubocop --auto-gen-config`
-# on 2014-11-29 13:48:01 -0500 using RuboCop version 0.27.0.
+# on 2015-02-26 15:04:26 +0100 using RuboCop version 0.27.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 8
+# Offense count: 9
 Metrics/AbcSize:
-  Max: 327
+  Max: 347
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 397
+  Max: 485
 
-# Offense count: 5
+# Offense count: 6
 Metrics/CyclomaticComplexity:
-  Max: 93
+  Max: 99
 
-# Offense count: 195
+# Offense count: 289
 # Configuration parameters: AllowURI, URISchemes.
 Metrics/LineLength:
   Max: 254
 
-# Offense count: 13
+# Offense count: 17
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 359
+  Max: 368
 
-# Offense count: 4
+# Offense count: 5
 Metrics/PerceivedComplexity:
-  Max: 96
+  Max: 101
 
-# Offense count: 7
+# Offense count: 8
 Style/ClassVars:
   Enabled: false
 
-# Offense count: 69
+# Offense count: 76
 Style/Documentation:
   Enabled: false
 

data/.travis.yml

@@ -13,4 +13,5 @@ env:
   - GRAPE_VERSION=0.8.0
   - GRAPE_VERSION=0.9.0
   - GRAPE_VERSION=0.10.0
+  - GRAPE_VERSION=0.10.1
   - GRAPE_VERSION=HEAD

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+### 0.10.0 (March 10, 2015)
+
+#### Features
+
+* [#217](https://github.com/tim-vandecasteele/grape-swagger/pull/217): Support Array of entities for proper rendering of grape-entity input dependencies - [@swistaczek](https://github.com/swistaczek).
+* [#214](https://github.com/tim-vandecasteele/grape-swagger/pull/214): Allow anything that responds to `call` to be used in `:hidden` - [@zbelzer](https://github.com/zbelzer).
+* [#196](https://github.com/tim-vandecasteele/grape-swagger/pull/196): If `:type` is omitted, see if it's available in `:using` - [@jhollinger](https://github.com/jhollinger).
+* [#200](https://github.com/tim-vandecasteele/grape-swagger/pull/200): Treat `type: Symbol` as string form parameter - [@ypresto](https://github.com/ypresto).
+* [#207](https://github.com/tim-vandecasteele/grape-swagger/pull/207): Support grape `mutually_exclusive` - [@mintuhouse](https://github.com/mintuhouse).
+* [#220](https://github.com/tim-vandecasteele/grape-swagger/pull/220): Support standalone appearance of namespace routes with a custom name instead of forced nesting - [@croeck](https://github.com/croeck).
+
+#### Fixes
+
+* [#221](https://github.com/tim-vandecasteele/grape-swagger/pull/221): Fixed group parameters' name with type Array - [@u2](https://github.com/u2).
+* [#211](https://github.com/tim-vandecasteele/grape-swagger/pull/211): Fixed the dependency, just `require 'grape'` - [@u2](https://github.com/u2).
+* [#210](https://github.com/tim-vandecasteele/grape-swagger/pull/210): Fixed the range `:values` option, now exposed as `enum` parameters - [@u2](https://github.com/u2).
+* [#208](https://github.com/tim-vandecasteele/grape-swagger/pull/208): Fixed `Float` parameters, exposed as Swagger `float` types - [@u2](https://github.com/u2).
+* [#216](https://github.com/tim-vandecasteele/grape-swagger/pull/216), [#192](https://github.com/tim-vandecasteele/grape-swagger/issues/192), [#189](https://github.com/tim-vandecasteele/grape-swagger/issues/189): Fixed API route paths matching for root endpoints with `grape ~> 0.10.0`, specific `format` and `:path` versioning - [@dm1try](https://github.com/dm1try), [@minch](https://github.com/minch).
+
 ### 0.9.0 (December 19, 2014)
 
 * [#91](https://github.com/tim-vandecasteele/grape-swagger/issues/91): Fixed empty field for group parameters' name with type hash or Array - [@dukedave](https://github.com/dukedave).

data/README.md

@@ -1,6 +1,8 @@
 # grape-swagger
 
-[![Build Status](https://travis-ci.org/tim-vandecasteele/grape-swagger.svg?branch=master)](https://travis-ci.org/tim-vandecasteele/grape-swagger)
+[![Gem Version](http://img.shields.io/gem/v/grape-swagger.svg)](http://badge.fury.io/rb/grape-swagger)
+[![Build Status](http://img.shields.io/travis/tim-vandecasteele/grape-swagger.svg)](https://travis-ci.org/tim-vandecasteele/grape-swagger)
+[![Code Climate](https://codeclimate.com/github/tim-vandecasteele/grape-swagger.svg)](https://codeclimate.com/github/tim-vandecasteele/grape-swagger)
 
 ## What is grape-swagger?
 
@@ -174,6 +176,13 @@ You can hide an endpoint by adding ```hidden: true``` in the description of the
 desc 'Hide this endpoint', hidden: true
 ```
 
+Endpoints can be conditionally hidden by providing a callable object such as a lambda which evaluates to the desired
+state:
+
+``` ruby
+desc 'Conditionally hide this endpoint', hidden: lambda { ENV['EXPERIMENTAL'] != 'true' }
+```
+
 ## Overriding Auto-Generated Nicknames
 
 You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'``` in the description of the endpoint.
@@ -182,6 +191,44 @@ You can specify a swagger nickname to use instead of the auto generated name by
 desc 'Get a full list of pets', nickname: 'getAllPets'
 ```
 
+## Expose nested namespace as standalone route
+Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.
+This option can help to structure and keep the swagger schema simple.
+
+    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
+      get :order_id do
+      	...
+      end
+    end
+    
+All routes that belong to this namespace (here: the `GET /order_id`) will then be assigned to the `store_order` route instead of the `store` resource route.
+    
+It is also possible to expose a namspace within another already exposed namespace:
+
+    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
+      get :order_id do
+      	...
+      end
+      namespace 'actions', desc: 'Order actions' do, nested: false
+        get 'evaluate' do
+          ...
+        end
+      end
+    end
+
+Here, the `GET /order_id` appears as operation of the `store_order` resource and the `GET /evaluate` as operation of the `store_orders_actions` route.
+
+### With a custom name
+Auto generated names for the standalone version of complex nested resource do not have a nice look.
+You can set a custom name with the `name` property inside the `swagger` option, but only if the namespace gets exposed as standalone route.
+The name should not contain whitespaces or any other special characters due to further issues within swagger-ui.
+
+    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false, name: 'Store-orders' } do
+      get :order_id do
+      	...
+      end
+    end
+
 ## Grape Entities
 
 Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
@@ -227,7 +274,7 @@ end
 
 ### Relationships
 
-Put the full name of the relationship's class in `type`, leaving out any modules named `Entities` or `Entity`. So for the entity class `API::Entities::Address`, you would put `type: 'API::Address'`.
+You may safely omit `type` from relationships, as it can be inferred. However, if you need to specify or override it, use the full name of the class leaving out any modules named `Entities` or `Entity`.
 
 #### 1xN
 

data/UPGRADING.md

@@ -1,6 +1,26 @@
 Upgrading Grape-swagger
 =======================
 
+### Upgrading to >= 0.9.0
+
+#### Changes in Configuration
+
+If you're using [grape-swagger-rails](https://github.com/BrandyMint/grape-swagger-rails), remove the `.json` extension from `GrapeSwaggerRails.options.url`.
+
+For example, change 
+
+```ruby
+GrapeSwaggerRails.options.url = '/api/v1/swagger_doc.json'
+```
+
+to
+
+```ruby
+GrapeSwaggerRails.options.url = '/api/v1/swagger_doc'
+```
+
+See [#187](https://github.com/tim-vandecasteele/grape-swagger/issues/187) for more information.
+
 ### Upgrading to >= 0.8.0
 
 #### Changes in Configuration

data/lib/grape-swagger.rb

@@ -1,3 +1,4 @@
+require 'grape'
 require 'grape-swagger/version'
 require 'grape-swagger/errors'
 require 'grape-swagger/markdown'
@@ -7,7 +8,7 @@ require 'grape-swagger/markdown/redcarpet_adapter'
 module Grape
   class API
     class << self
-      attr_reader :combined_routes, :combined_namespaces
+      attr_reader :combined_routes, :combined_namespaces, :combined_namespace_routes, :combined_namespace_identifiers
 
       def add_swagger_documentation(options = {})
         documentation_class = create_documentation_class
@@ -20,7 +21,7 @@ module Grape
           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|-]*)')
+          route_match = route_match.match('\/([\w|-]*?)[\.\/\(]') || route_match.match('\/([\w|-]*)$')
           next unless route_match
           resource = route_match.captures.first
           next if resource.empty?
@@ -32,6 +33,13 @@ module Grape
 
         @combined_namespaces = {}
         combine_namespaces(self)
+
+        @combined_namespace_routes = {}
+        @combined_namespace_identifiers = {}
+        combine_namespace_routes(@combined_namespaces)
+
+        exclusive_route_keys = @combined_routes.keys - @combined_namespaces.keys
+        exclusive_route_keys.each { |key| @combined_namespace_routes[key] = @combined_routes[key] }
         documentation_class
       end
 
@@ -44,12 +52,112 @@ module Grape
                else
                  endpoint.settings.stack.last[:namespace]
                end
-          @combined_namespaces[ns.space] = ns if ns
+          # use the full namespace here (not the latest level only)
+          # and strip leading slash
+          @combined_namespaces[endpoint.namespace.sub(/^\//, '')] = ns if ns
 
           combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
         end
       end
 
+      def combine_namespace_routes(namespaces)
+        # iterate over each single namespace
+        namespaces.each do |name, namespace|
+          # get the parent route for the namespace
+          parent_route_name = name.match(%r{^/?([^/]*).*$})[1]
+          parent_route = @combined_routes[parent_route_name]
+          # fetch all routes that are within the current namespace
+          namespace_routes = parent_route.collect do |route|
+            route if (route.route_path.start_with?("/#{name}") || route.route_path.start_with?("/:version/#{name}")) &&
+                     (route.instance_variable_get(:@options)[:namespace] == "/#{name}" || route.instance_variable_get(:@options)[:namespace] == "/:version/#{name}")
+          end.compact
+
+          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
+            if namespace.options[:swagger].key?(:name)
+              identifier = namespace.options[:swagger][:name].gsub(/ /, '-')
+            else
+              identifier = name.gsub(/_/, '-').gsub(/\//, '_')
+            end
+            @combined_namespace_identifiers[identifier] = name
+            @combined_namespace_routes[identifier] = namespace_routes
+
+            # 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
+            @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 }
+            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?
+              # default option, append namespace methods to parent route
+              @combined_namespace_routes[parent_route_name] = [] unless @combined_namespace_routes.key?(parent_route_name)
+              @combined_namespace_routes[parent_route_name].push(*namespace_routes)
+            end
+          end
+        end
+      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)
+        sub_namespaces = {}
+        # fetch all namespaces that are children of the current namespace
+        namespaces.each { |ns_name, ns| sub_namespaces[ns_name] = ns if ns_name.start_with?(name) && ns_name != name }
+        # remove the sub namespaces if they are assigned to another standalone namespace themselves
+        sub_namespaces.each do |sub_name, sub_ns|
+          # skip if sub_ns is standalone, too
+          next unless sub_ns.options.key?(:swagger) && sub_ns.options[:swagger][:nested] == false
+          # remove all namespaces that are nested below this standalone sub_ns
+          sub_namespaces.each { |sub_sub_name, _| sub_namespaces.delete(sub_sub_name) if sub_sub_name.start_with?(sub_name) }
+        end
+        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(Hash.new) 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_param = nil
+        params.each_key do |k|
+          if params[k].is_a?(Hash) && params[k][:type] == 'Array'
+            array_param = k
+          else
+            new_key = k
+            unless array_param.nil?
+              if k.to_s.start_with?(array_param.to_s + '[')
+                new_key = array_param.to_s + '[]' + k.to_s.split(array_param)[1]
+              end
+            end
+            modified_params[new_key] = params[k]
+          end
+        end
+        modified_params
+      end
+
       def create_documentation_class
         Class.new(Grape::API) do
           class << self
@@ -64,10 +172,9 @@ module Grape
             def parse_params(params, path, method)
               params ||= []
 
-              non_nested_parent_params = params.reject do |param, _|
-                is_nested_param = /^#{ Regexp.quote param }\[.+\]$/
-                params.keys.any? { |p| p.match is_nested_param }
-              end
+              parsed_array_params = parse_array_params(params)
+
+              non_nested_parent_params = get_non_nested_params(parsed_array_params)
 
               non_nested_parent_params.map do |param, value|
                 items = {}
@@ -80,7 +187,7 @@ module Grape
                                   'File'
                                 when 'Virtus::Attribute::Boolean'
                                   'boolean'
-                                when 'Boolean', 'Date', 'Integer', 'String'
+                                when 'Boolean', 'Date', 'Integer', 'String', 'Float'
                                   raw_data_type.downcase
                                 when 'BigDecimal'
                                   'long'
@@ -88,6 +195,8 @@ module Grape
                                   'dateTime'
                                 when 'Numeric'
                                   'double'
+                                when 'Symbol'
+                                  'string'
                                 else
                                   @@documentation_class.parse_entity_name(raw_data_type)
                                 end
@@ -96,6 +205,7 @@ module Grape
                 default_value = value.is_a?(Hash) ? value[:default] : nil
                 is_array      = value.is_a?(Hash) ? (value[:is_array] || false) : false
                 enum_values   = value.is_a?(Hash) ? value[:values] : nil
+                enum_values   = enum_values.to_a if enum_values && enum_values.is_a?(Range)
                 enum_values   = enum_values.call if enum_values && enum_values.is_a?(Proc)
 
                 if value.is_a?(Hash) && value.key?(:param_type)
@@ -220,11 +330,17 @@ module Grape
 
                   required << property_name.to_s if p.delete(:required)
 
+                  type = if p[:type]
+                           p.delete(:type)
+                         elsif (entity = model.exposures[property_name][:using])
+                           parse_entity_name(entity)
+                         end
+
                   if p.delete(:is_array)
-                    p[:items] = generate_typeref(p[:type])
+                    p[:items] = generate_typeref(type)
                     p[:type] = 'array'
                   else
-                    p.merge! generate_typeref(p.delete(:type))
+                    p.merge! generate_typeref(type)
                   end
 
                   # rename Grape Entity's "desc" to "description"
@@ -239,7 +355,6 @@ module Grape
                   end
 
                   properties[property_name] = p
-
                 end
 
                 result[name] = {
@@ -372,20 +487,21 @@ module Grape
                 header['Access-Control-Allow-Origin']   = '*'
                 header['Access-Control-Request-Method'] = '*'
 
-                routes = target_class.combined_routes
                 namespaces = target_class.combined_namespaces
+                namespace_routes = target_class.combined_namespace_routes
 
                 if @@hide_documentation_path
-                  routes.reject! { |route, _value| "/#{route}/".index(@@documentation_class.parse_path(@@mount_path, nil) << '/') == 0 }
+                  namespace_routes.reject! { |route, _value| "/#{route}/".index(@@documentation_class.parse_path(@@mount_path, nil) << '/') == 0 }
                 end
 
-                routes_array = routes.keys.map do |local_route|
-                  next if routes[local_route].all?(&:route_hidden)
+                namespace_routes_array = namespace_routes.keys.map do |local_route|
+                  next if namespace_routes[local_route].map(&:route_hidden).all? { |value| value.respond_to?(:call) ? value.call : value }
 
                   url_format  = '.{format}' unless @@hide_format
 
-                  description = namespaces[local_route] && namespaces[local_route].options[:desc]
-                  description ||= "Operations about #{local_route.pluralize}"
+                  original_namespace_name = target_class.combined_namespace_identifiers.key?(local_route) ? target_class.combined_namespace_identifiers[local_route] : local_route
+                  description = namespaces[original_namespace_name] && namespaces[original_namespace_name].options[:desc]
+                  description ||= "Operations about #{original_namespace_name.pluralize}"
 
                   {
                     path: "/#{local_route}#{url_format}",
@@ -397,7 +513,7 @@ module Grape
                   apiVersion:     api_version,
                   swaggerVersion: '1.2',
                   produces:       @@documentation_class.content_types_for(target_class),
-                  apis:           routes_array,
+                  apis:           namespace_routes_array,
                   info:           @@documentation_class.parse_info(extra_info)
                 }
 
@@ -419,10 +535,14 @@ module Grape
                 header['Access-Control-Request-Method'] = '*'
 
                 models = []
-                routes = target_class.combined_routes[params[:name]]
+                routes = target_class.combined_namespace_routes[params[:name]]
                 error!('Not Found', 404) unless routes
 
-                ops = routes.reject(&:route_hidden).group_by do |route|
+                visible_ops = routes.reject do |route|
+                  route.route_hidden.respond_to?(:call) ? route.route_hidden.call : route.route_hidden
+                end
+
+                ops = visible_ops.group_by do |route|
                   @@documentation_class.parse_path(route.route_path, api_version)
                 end
 
@@ -438,7 +558,7 @@ module Grape
 
                     models |= @@models if @@models.present?
 
-                    models |= [route.route_entity] if route.route_entity.present?
+                    models |= Array(route.route_entity) if route.route_entity.present?
 
                     models = @@documentation_class.models_with_included_presenters(models.flatten.compact)
 
@@ -457,7 +577,7 @@ module Grape
                     operation.merge!(responseMessages: http_codes) unless http_codes.empty?
 
                     if route.route_entity
-                      type = @@documentation_class.parse_entity_name(route.route_entity)
+                      type = @@documentation_class.parse_entity_name(Array(route.route_entity).first)
                       operation.merge!('type' => type)
                     end
 
@@ -470,10 +590,16 @@ module Grape
                   }
                 end
 
+                # use custom resource naming if available
+                if target_class.combined_namespace_identifiers.key? params[:name]
+                  resource_path = target_class.combined_namespace_identifiers[params[:name]]
+                else
+                  resource_path = params[:name]
+                end
                 api_description = {
                   apiVersion:     api_version,
                   swaggerVersion: '1.2',
-                  resourcePath:   "/#{params[:name]}",
+                  resourcePath:   "/#{resource_path}",
                   produces:       @@documentation_class.content_types_for(target_class),
                   apis:           apis
                 }