grape-swagger 0.24.0 → 0.25.0

data/UPGRADING.md

@@ -1,6 +1,10 @@
 Upgrading Grape-swagger
 =======================
 
+### Upgrading to >= 0.25.0
+
+The global tag set now only includes tags for documented routes. This behaviour has impact in particular for calling the documtation of a specific route.
+
 ### 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:

data/grape-swagger.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.authors     = ['Tim Vandecasteele']
   s.email       = ['tim.vandecasteele@gmail.com']
   s.homepage    = 'https://github.com/ruby-grape/grape-swagger'
-  s.summary     = 'A simple way to add auto generated documentation to your Grape API that can be displayed with Swagger.'
+  s.summary     = 'Add auto generated documentation to your Grape API that can be displayed with Swagger.'
   s.license     = 'MIT'
 
   s.add_runtime_dependency 'grape', '>= 0.12.0'
@@ -20,7 +20,7 @@ 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.40.0'
+  s.add_development_dependency 'rubocop', '~> 0.40'
   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')

data/lib/grape-swagger.rb

@@ -52,7 +52,9 @@ module Grape
         combine_namespace_routes(@target_class.combined_namespaces)
 
         exclusive_route_keys = @target_class.combined_routes.keys - @target_class.combined_namespaces.keys
-        exclusive_route_keys.each { |key| @target_class.combined_namespace_routes[key] = @target_class.combined_routes[key] }
+        exclusive_route_keys.each do |key|
+          @target_class.combined_namespace_routes[key] = @target_class.combined_routes[key]
+        end
         documentation_class
       end
 
@@ -128,10 +130,12 @@ module Grape
             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
+            # 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
-              @target_class.combined_namespace_routes[parent_route_name] = [] unless @target_class.combined_namespace_routes.key?(parent_route_name)
+              parent_route = @target_class.combined_namespace_routes.key?(parent_route_name)
+              @target_class.combined_namespace_routes[parent_route_name] = [] unless parent_route
               @target_class.combined_namespace_routes[parent_route_name].push(*namespace_routes)
             end
           end
@@ -175,7 +179,9 @@ module Grape
           # 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) }
+          sub_namespaces.each do |sub_sub_name, _|
+            sub_namespaces.delete(sub_sub_name) if sub_sub_name.start_with?(sub_name)
+          end
         end
         sub_namespaces
       end

data/lib/grape-swagger/doc_methods.rb

@@ -10,6 +10,7 @@ require 'grape-swagger/doc_methods/tag_name_description'
 require 'grape-swagger/doc_methods/parse_params'
 require 'grape-swagger/doc_methods/move_params'
 require 'grape-swagger/doc_methods/headers'
+require 'grape-swagger/doc_methods/build_model_definition'
 
 module GrapeSwagger
   module DocMethods
@@ -36,9 +37,11 @@ module GrapeSwagger
 
       class_variables_from(options)
 
-      [:format, :default_format, :default_error_formatter].each do |method|
-        send(method, formatter)
-      end if formatter
+      if formatter
+        [:format, :default_format, :default_error_formatter].each do |method|
+          send(method, formatter)
+        end
+      end
 
       send(guard.split.first.to_sym, *guard.split(/[\s,]+/).drop(1)) unless guard.nil?
 
@@ -49,7 +52,9 @@ module GrapeSwagger
           options
         )
 
-        paths, definitions = endpoint.path_and_definition_objects(combi_routes, options)
+        paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
+        tags                 = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+        output[:tags]        = tags unless tags.empty? || paths.blank?
         output[:paths]       = paths unless paths.blank?
         output[:definitions] = definitions unless definitions.blank?
 
@@ -97,7 +102,7 @@ module GrapeSwagger
         specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
         endpoint_auth_wrapper: nil,
         swagger_endpoint_guard: nil,
-        oauth_token: nil
+        token_owner: nil
       }
     end
 

data/lib/grape-swagger/doc_methods/build_model_definition.rb

@@ -0,0 +1,38 @@
+module GrapeSwagger
+  module DocMethods
+    class BuildModelDefinition
+      class << self
+        def build(model, properties)
+          definition = { type: 'object', properties: properties }
+
+          required = required_attributes(model)
+          definition[:required] = required unless required.blank?
+
+          definition
+        end
+
+        private
+
+        def required_attributes(model)
+          parse_entity(model) || parse_representable(model)
+        end
+
+        def parse_entity(model)
+          return unless model.respond_to?(:documentation)
+
+          model.documentation
+               .select { |_name, options| options[:required] }
+               .map { |name, options| options[:as] || name }
+        end
+
+        def parse_representable(model)
+          return unless model.respond_to?(:map)
+
+          model.map
+               .select { |p| p[:documentation] && p[:documentation][:required] }
+               .map(&:name)
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/data_type.rb

@@ -41,13 +41,14 @@ module GrapeSwagger
         end
 
         def parse_entity_name(model)
-          if model.respond_to?(:entity_name)
+          if model.methods(false).include?(:entity_name)
             model.entity_name
+          elsif model.to_s.end_with?('::Entity', '::Entities')
+            model.to_s.split('::')[-2]
+          elsif model.respond_to?(:name)
+            model.name.demodulize.camelize
           else
-            name = model.to_s
-            entity_parts = name.split('::')
-            entity_parts.reject! { |p| p == 'Entity' || p == 'Entities' }
-            entity_parts.join('::')
+            model.to_s.split('::').last
           end
         end
 

data/lib/grape-swagger/doc_methods/move_params.rb

@@ -74,7 +74,15 @@ module GrapeSwagger
         end
 
         def document_as_property(param)
-          property_keys.each_with_object({}) { |x, memo| memo[x] = param[x] if param[x].present? }
+          property_keys.each_with_object({}) do |x, memo|
+            value = param[x]
+            next if value.blank?
+            if x == :type && @definitions[value].present?
+              memo['$ref'] = "#/definitions/#{value}"
+            else
+              memo[x] = value
+            end
+          end
         end
 
         def build_nested_properties(params, properties = {})

data/lib/grape-swagger/doc_methods/optional_object.rb

@@ -12,7 +12,7 @@ module GrapeSwagger
         end
 
         def evaluate(key, options, request)
-          options[key].arity == 0 ? options[key].call : options[key].call(request)
+          options[key].arity.zero? ? options[key].call : options[key].call(request)
         end
 
         def default_values

data/lib/grape-swagger/doc_methods/parse_params.rb

@@ -2,7 +2,7 @@ module GrapeSwagger
   module DocMethods
     class ParseParams
       class << self
-        def call(param, settings, route)
+        def call(param, settings, route, definitions)
           path = route.path
           method = route.request_method
 
@@ -21,7 +21,7 @@ module GrapeSwagger
           # optional properties
           document_description(settings)
           document_type_and_format(data_type)
-          document_array_param(value_type)
+          document_array_param(value_type, definitions) if value_type[:is_array]
           document_default_value(settings)
           document_range_values(settings)
           document_required(settings)
@@ -60,25 +60,26 @@ module GrapeSwagger
           end
         end
 
-        def document_array_param(value_type)
-          if value_type[:is_array]
-            if value_type[:documentation].present?
-              param_type = value_type[:documentation][:param_type]
-              doc_type = value_type[:documentation][:type]
-              type = GrapeSwagger::DocMethods::DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
-              collection_format = value_type[:documentation][:collectionFormat]
-            end
-
-            array_items = {
-              type: type || @parsed_param[:type],
-              format: @parsed_param.delete(:format)
-            }.delete_if { |_, value| value.blank? }
+        def document_array_param(value_type, definitions)
+          if value_type[:documentation].present?
+            param_type = value_type[:documentation][:param_type]
+            doc_type = value_type[:documentation][:type]
+            type = GrapeSwagger::DocMethods::DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
+            collection_format = value_type[:documentation][:collectionFormat]
+          end
 
-            @parsed_param[:in] = param_type || 'formData'
-            @parsed_param[:items] = array_items
-            @parsed_param[:type] = 'array'
-            @parsed_param[:collectionFormat] = collection_format if %w(csv ssv tsv pipes multi).include?(collection_format)
+          array_items = {}
+          if definitions[value_type[:data_type]]
+            array_items['$ref'] = "#/definitions/#{@parsed_param[:type]}"
+          else
+            array_items[:type] = type || @parsed_param[:type]
           end
+          array_items[:format] = @parsed_param.delete(:format) if @parsed_param[:format]
+
+          @parsed_param[:in] = param_type || 'formData'
+          @parsed_param[:items] = array_items
+          @parsed_param[:type] = 'array'
+          @parsed_param[:collectionFormat] = collection_format if %w(csv ssv tsv pipes multi).include?(collection_format)
         end
 
         def param_type(value_type)

data/lib/grape-swagger/doc_methods/tag_name_description.rb

@@ -2,23 +2,15 @@ module GrapeSwagger
   module DocMethods
     class TagNameDescription
       class << self
-        def build(options = {})
-          target_class = options[:target_class]
-          namespaces = target_class.combined_namespaces
-          namespace_routes = target_class.combined_namespace_routes
-
-          namespace_routes.keys.map do |local_route|
-            next if namespace_routes[local_route].map { |route| route.options[:hidden] }.all? { |value| value.respond_to?(:call) ? value.call : value }
-
-            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}"
-
-            {
-              name: local_route,
-              description: description
-            }
-          end.compact
+        def build(paths)
+          paths.values.each_with_object([]) do |path, memo|
+            path.values.first[:tags].each do |tag|
+              memo << {
+                name: tag,
+                description: "Operations about #{tag.pluralize}"
+              }
+            end
+          end.uniq
         end
       end
     end

data/lib/grape-swagger/endpoint.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'active_support'
 require 'active_support/core_ext/string/inflections.rb'
 
@@ -29,7 +27,6 @@ module Grape
         securityDefinitions: options[:security_definitions],
         host:           GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
         basePath:       GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
-        tags:           GrapeSwagger::DocMethods::TagNameDescription.build(options),
         schemes:        options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
       }.delete_if { |_, value| value.blank? }
     end
@@ -112,7 +109,7 @@ module Grape
       method[:parameters]  = params_object(route)
       method[:security]    = security_object(route)
       method[:responses]   = response_object(route, options[:markdown])
-      method[:tags]        = tag_object(route)
+      method[:tags]        = route.options.fetch(:tags, tag_object(route))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method.delete_if { |_, value| value.blank? }
 
@@ -164,7 +161,12 @@ module Grape
       parameters = partition_params(route).map do |param, value|
         value = { required: false }.merge(value) if value.is_a?(Hash)
         _, value = default_type([[param, value]]).first if value == ''
-        GrapeSwagger::DocMethods::ParseParams.call(param, value, route)
+        if value[:type]
+          expose_params(value[:type])
+        elsif value[:documentation]
+          expose_params(value[:documentation][:type])
+        end
+        GrapeSwagger::DocMethods::ParseParams.call(param, value, route, @definitions)
       end
 
       if GrapeSwagger::DocMethods::MoveParams.can_be_moved?(parameters, route.request_method)
@@ -262,49 +264,44 @@ module Grape
       param_types.size == 1
     end
 
+    def expose_params(value)
+      if value.is_a?(Class) && GrapeSwagger.model_parsers.find(value)
+        expose_params_from_model(value)
+      elsif value.is_a?(String)
+        begin
+          expose_params(Object.const_get(value.gsub(/\[|\]/, ''))) # try to load class from its name
+        rescue NameError
+          nil
+        end
+      end
+    end
+
     def expose_params_from_model(model)
+      model = model.is_a?(String) ? model.constantize : model
       model_name = model_name(model)
 
       return model_name if @definitions.key?(model_name)
       @definitions[model_name] = nil
 
-      properties = nil
-      parser = nil
-
-      GrapeSwagger.model_parsers.each do |klass, ancestor|
-        next unless model.ancestors.map(&:to_s).include?(ancestor)
-        parser = klass.new(model, self)
-        break
-      end
-
-      properties = parser.call unless parser.nil?
-
+      parser = GrapeSwagger.model_parsers.find(model)
       raise GrapeSwagger::Errors::UnregisteredParser, "No parser registered for #{model_name}." unless parser
+
+      properties = parser.new(model, self).call
       raise GrapeSwagger::Errors::SwaggerSpec, "Empty model #{model_name}, swagger 2.0 doesn't support empty definitions." unless properties && properties.any?
 
-      @definitions[model_name] = { type: 'object', properties: properties }
+      @definitions[model_name] = GrapeSwagger::DocMethods::BuildModelDefinition.build(model, properties)
 
       model_name
     end
 
     def model_name(name)
-      if name.respond_to?(:entity_name)
-        name.entity_name
-      elsif name.to_s.end_with?('Entity', 'Entities')
-        length = 0
-        name.to_s.split('::')[0..-2].reverse.take_while do |x|
-          length += x.length
-          length < 42
-        end.reverse.join
-      else
-        name.name.demodulize.camelize
-      end
+      GrapeSwagger::DocMethods::DataType.parse_entity_name(name)
     end
 
     def hidden?(route, options)
       route_hidden = route.options[:hidden]
       return route_hidden unless route_hidden.is_a?(Proc)
-      options[:oauth_token] ? route_hidden.call(send(options[:oauth_token].to_sym)) : route_hidden.call
+      options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
     end
 
     def public_parameter?(param)

data/lib/grape-swagger/model_parsers.rb

@@ -29,5 +29,12 @@ module GrapeSwagger
         yield klass, ancestor
       end
     end
+
+    def find(model)
+      GrapeSwagger.model_parsers.each do |klass, ancestor|
+        return klass if model.ancestors.map(&:to_s).include?(ancestor)
+      end
+      nil
+    end
   end
 end

data/lib/grape-swagger/version.rb

@@ -1,3 +1,3 @@
 module GrapeSwagger
-  VERSION = '0.24.0'.freeze
+  VERSION = '0.25.0'.freeze
 end

data/spec/issues/427_entity_as_string_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'grape-entity'
+require 'grape-swagger-entity'
+
+describe '#427 nested entity given as string' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_427 do
+        module Permission
+          class WithoutRole < Grape::Entity
+            expose :id
+            expose :description
+          end
+        end
+
+        class RoleEntity < Grape::Entity
+          expose :id
+          expose :description
+          expose :role
+          expose :permissions, using: 'Permission::WithoutRole'
+        end
+        desc 'Get a list of roles',
+             success: RoleEntity
+        get '/' do
+          present [], with: RoleEntity
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['definitions']
+  end
+
+  specify { expect(subject.keys).to include 'RoleEntity', 'WithoutRole' }
+end