grape-swagger 1.1.0 → 1.4.2

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

@@ -4,8 +4,8 @@ module GrapeSwagger
   module DocMethods
     class BuildModelDefinition
       class << self
-        def build(model, properties, required)
-          definition = { type: 'object', properties: properties }
+        def build(model, properties, required, other_def_properties = {})
+          definition = { type: 'object', properties: properties }.merge(other_def_properties)
 
           if required.nil?
             required_attrs = required_attributes(model)
@@ -17,6 +17,57 @@ module GrapeSwagger
           definition
         end
 
+        def parse_params_from_model(parsed_response, model, model_name)
+          if parsed_response.is_a?(Hash) && parsed_response.keys.first == :allOf
+            refs_or_models = parsed_response[:allOf]
+            parsed = parse_refs_and_models(refs_or_models, model)
+
+            {
+              allOf: parsed
+            }
+          else
+            properties, required = parsed_response
+            unless properties&.any?
+              raise GrapeSwagger::Errors::SwaggerSpec,
+                    "Empty model #{model_name}, swagger 2.0 doesn't support empty definitions."
+            end
+            properties, other_def_properties = parse_properties(properties)
+
+            build(
+              model, properties, required, other_def_properties
+            )
+          end
+        end
+
+        def parse_properties(properties)
+          other_properties = {}
+
+          discriminator_key, discriminator_value =
+            properties.find do |_key, value|
+              value[:documentation].try(:[], :is_discriminator)
+            end
+
+          if discriminator_key
+            discriminator_value.delete(:documentation)
+            properties[discriminator_key] = discriminator_value
+
+            other_properties[:discriminator] = discriminator_key
+          end
+
+          [properties, other_properties]
+        end
+
+        def parse_refs_and_models(refs_or_models, model)
+          refs_or_models.map do |ref_or_models|
+            if ref_or_models.is_a?(Hash) && ref_or_models.keys.first == '$ref'
+              ref_or_models
+            else
+              properties, required = ref_or_models
+              GrapeSwagger::DocMethods::BuildModelDefinition.build(model, properties, required)
+            end
+          end
+        end
+
         private
 
         def required_attributes(model)

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

@@ -48,14 +48,14 @@ module GrapeSwagger
         end
 
         def parse_entity_name(model)
-          if model.methods(false).include?(:entity_name)
+          if model.respond_to?(:entity_name)
             model.entity_name
           elsif model.to_s.end_with?('::Entity', '::Entities')
-            model.to_s.split('::')[0..-2].join('::')
+            model.to_s.split('::')[0..-2].join('_')
           elsif model.to_s.start_with?('Entity::', 'Entities::', 'Representable::')
-            model.to_s.split('::')[1..-1].join('::')
+            model.to_s.split('::')[1..-1].join('_')
           else
-            model.to_s
+            model.to_s.split('::').join('_')
           end
         end
 

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

@@ -7,7 +7,7 @@ module GrapeSwagger
         def to_format(parameters)
           parameters.reject { |parameter| parameter[:in] == 'body' }.each do |b|
             related_parameters = parameters.select do |p|
-              p[:name] != b[:name] && p[:name].to_s.include?(b[:name].to_s.gsub(/\[\]\z/, '') + '[')
+              p[:name] != b[:name] && p[:name].to_s.start_with?("#{b[:name].to_s.gsub(/\[\]\z/, '')}[")
             end
             parameters.reject! { |p| p[:name] == b[:name] } if move_down(b, related_parameters)
           end
@@ -30,11 +30,13 @@ module GrapeSwagger
 
         def add_braces(parameter, related_parameters)
           param_name = parameter[:name].gsub(/\A(.*)\[\]\z/, '\1')
-          related_parameters.each { |p| p[:name] = p[:name].gsub(param_name, param_name + '[]') }
+          related_parameters.each { |p| p[:name] = p[:name].gsub(param_name, "#{param_name}[]") }
         end
 
         def add_array(parameter, related_parameters)
           related_parameters.each do |p|
+            next if p.key?(:items)
+
             p_type = p[:type] == 'array' ? 'string' : p[:type]
             p[:items] = { type: p_type, format: p[:format], enum: p[:enum], is_array: p[:is_array] }
             p[:items].delete_if { |_k, v| v.nil? }

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

@@ -103,9 +103,9 @@ module GrapeSwagger
 
         def document_as_property(param)
           property_keys.each_with_object({}) do |x, memo|
-            value = param[x]
-            next if value.blank?
+            next unless param.key?(x)
 
+            value = param[x]
             if x == :type && @definitions[value].present?
               memo['$ref'] = "#/definitions/#{value}"
             else
@@ -181,7 +181,8 @@ module GrapeSwagger
         end
 
         def property_keys
-          %i[type format description minimum maximum items enum default additionalProperties]
+          %i[type format description minimum maximum items enum default additional_properties additionalProperties
+             example]
         end
 
         def deletable?(param)
@@ -193,8 +194,7 @@ module GrapeSwagger
         end
 
         def includes_body_param?(params)
-          params.map { |x| return true if x[:in] == 'body' || x[:param_type] == 'body' }
-          false
+          params.any? { |x| x[:in] == 'body' || x[:param_type] == 'body' }
         end
 
         def should_expose_as_array?(params)
@@ -202,8 +202,7 @@ module GrapeSwagger
         end
 
         def should_exposed_as(params)
-          params.map { |x| return 'object' if x[:type] && x[:type] != 'array' }
-          'array'
+          params.any? { |x| x[:type] && x[:type] != 'array' } ? 'object' : 'array'
         end
       end
     end

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

@@ -16,8 +16,8 @@ module GrapeSwagger
 
         def manipulate(path)
           operation = path.split('/').map(&:capitalize).join
-          operation.gsub!(/\-(\w)/, &:upcase).delete!('-') if operation[/\-(\w)/]
-          operation.gsub!(/\_(\w)/, &:upcase).delete!('_') if operation.include?('_')
+          operation.gsub!(/-(\w)/, &:upcase).delete!('-') if operation[/-(\w)/]
+          operation.gsub!(/_(\w)/, &:upcase).delete!('_') if operation.include?('_')
           operation.gsub!(/\.(\w)/, &:upcase).delete!('.') if operation[/\.(\w)/]
           if path.include?('{')
             operation.gsub!(/\{(\w)/, &:upcase)

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

@@ -25,8 +25,9 @@ module GrapeSwagger
           document_default_value(settings) unless value_type[:is_array]
           document_range_values(settings) unless value_type[:is_array]
           document_required(settings)
-          document_additional_properties(settings)
+          document_additional_properties(definitions, settings) unless value_type[:is_array]
           document_add_extensions(settings)
+          document_example(settings)
 
           @parsed_param
         end
@@ -50,7 +51,7 @@ module GrapeSwagger
         end
 
         def document_default_value(settings)
-          @parsed_param[:default] = settings[:default] if settings[:default].present?
+          @parsed_param[:default] = settings[:default] if settings.key?(:default)
         end
 
         def document_type_and_format(settings, data_type)
@@ -77,6 +78,19 @@ module GrapeSwagger
 
           param_type ||= value_type[:param_type]
 
+          array_items = parse_array_item(
+            definitions,
+            type,
+            value_type
+          )
+
+          @parsed_param[:in] = param_type || 'formData'
+          @parsed_param[:items] = array_items
+          @parsed_param[:type] = 'array'
+          @parsed_param[:collectionFormat] = collection_format if DataType.collections.include?(collection_format)
+        end
+
+        def parse_array_item(definitions, type, value_type)
           array_items = {}
           if definitions[value_type[:data_type]]
             array_items['$ref'] = "#/definitions/#{@parsed_param[:type]}"
@@ -91,15 +105,43 @@ module GrapeSwagger
 
           array_items[:default] = value_type[:default] if value_type[:default].present?
 
-          @parsed_param[:in] = param_type || 'formData'
-          @parsed_param[:items] = array_items
-          @parsed_param[:type] = 'array'
-          @parsed_param[:collectionFormat] = collection_format if DataType.collections.include?(collection_format)
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, value_type)
+          array_items[:additionalProperties] = additional_properties if set_additional_properties
+
+          array_items
+        end
+
+        def document_additional_properties(definitions, settings)
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, settings)
+          @parsed_param[:additionalProperties] = additional_properties if set_additional_properties
+        end
+
+        def parse_additional_properties(definitions, settings)
+          return false unless settings.key?(:additionalProperties) || settings.key?(:additional_properties)
+
+          value =
+            if settings.key?(:additionalProperties)
+              GrapeSwagger::Errors::SwaggerSpecDeprecated.tell!(:additionalProperties)
+              settings[:additionalProperties]
+            else
+              settings[:additional_properties]
+            end
+
+          parsed_value =
+            if definitions[value.to_s]
+              { '$ref': "#/definitions/#{value}" }
+            elsif value.is_a?(Class)
+              { type: DataType.call(value) }
+            else
+              value
+            end
+
+          [true, parsed_value]
         end
 
-        def document_additional_properties(settings)
-          additional_properties = settings[:additionalProperties]
-          @parsed_param[:additionalProperties] = additional_properties if additional_properties
+        def document_example(settings)
+          example = settings[:example]
+          @parsed_param[:example] = example if example
         end
 
         def param_type(value_type)

data/lib/grape-swagger/doc_methods.rb

@@ -17,6 +17,61 @@ require 'grape-swagger/doc_methods/version'
 
 module GrapeSwagger
   module DocMethods
+    DEFAULTS =
+      {
+        info: {},
+        models: [],
+        doc_version: '0.0.1',
+        target_class: nil,
+        mount_path: '/swagger_doc',
+        host: nil,
+        base_path: nil,
+        add_base_path: false,
+        add_version: true,
+        add_root: false,
+        hide_documentation_path: true,
+        format: :json,
+        authorizations: nil,
+        security_definitions: nil,
+        security: nil,
+        api_documentation: { desc: 'Swagger compatible API description' },
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
+        endpoint_auth_wrapper: nil,
+        swagger_endpoint_guard: nil,
+        token_owner: nil
+      }.freeze
+
+    FORMATTER_METHOD = %i[format default_format default_error_formatter].freeze
+
+    def self.output_path_definitions(combi_routes, endpoint, target_class, options)
+      output = endpoint.swagger_object(
+        target_class,
+        endpoint.request,
+        options
+      )
+
+      paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
+      tags                 = tags_from(paths, options)
+
+      output[:tags]        = tags unless tags.empty? || paths.blank?
+      output[:paths]       = paths unless paths.blank?
+      output[:definitions] = definitions unless definitions.blank?
+
+      output
+    end
+
+    def self.tags_from(paths, options)
+      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+
+      if options[:tags]
+        names = options[:tags].map { |t| t[:name] }
+        tags.reject! { |t| names.include?(t[:name]) }
+        tags += options[:tags]
+      end
+
+      tags
+    end
+
     def hide_documentation_path
       @@hide_documentation_path
     end
@@ -26,54 +81,32 @@ module GrapeSwagger
     end
 
     def setup(options)
-      options = defaults.merge(options)
+      options = DEFAULTS.merge(options)
 
       # options could be set on #add_swagger_documentation call,
       # for available options see #defaults
       target_class     = options[:target_class]
       guard            = options[:swagger_endpoint_guard]
-      formatter        = options[:format]
       api_doc          = options[:api_documentation].dup
       specific_api_doc = options[:specific_api_documentation].dup
 
       class_variables_from(options)
 
-      if formatter
-        %i[format default_format default_error_formatter].each do |method|
-          send(method, formatter)
-        end
-      end
+      setup_formatter(options[:format])
 
       desc api_doc.delete(:desc), api_doc
 
-      output_path_definitions = proc do |combi_routes, endpoint|
-        output = endpoint.swagger_object(
-          target_class,
-          endpoint.request,
-          options
-        )
-
-        paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
-        tags                 = tags_from(paths, options)
-
-        output[:tags]        = tags unless tags.empty? || paths.blank?
-        output[:paths]       = paths unless paths.blank?
-        output[:definitions] = definitions unless definitions.blank?
-
-        output
-      end
-
       instance_eval(guard) unless guard.nil?
 
       get mount_path do
         header['Access-Control-Allow-Origin']   = '*'
         header['Access-Control-Request-Method'] = '*'
 
-        output_path_definitions.call(target_class.combined_namespace_routes, self)
+        GrapeSwagger::DocMethods
+          .output_path_definitions(target_class.combined_namespace_routes, self, target_class, options)
       end
 
-      desc specific_api_doc.delete(:desc), { params:
-        specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
+      desc specific_api_doc.delete(:desc), { params: specific_api_doc.delete(:params) || {}, **specific_api_doc }
 
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
@@ -88,51 +121,21 @@ module GrapeSwagger
         combined_routes = target_class.combined_namespace_routes[params[:name]]
         error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
 
-        output_path_definitions.call({ params[:name] => combined_routes }, self)
+        GrapeSwagger::DocMethods
+          .output_path_definitions({ params[:name] => combined_routes }, self, target_class, options)
       end
     end
 
-    def defaults
-      {
-        info: {},
-        models: [],
-        doc_version: '0.0.1',
-        target_class: nil,
-        mount_path: '/swagger_doc',
-        host: nil,
-        base_path: nil,
-        add_base_path: false,
-        add_version: true,
-        add_root: false,
-        hide_documentation_path: true,
-        format: :json,
-        authorizations: nil,
-        security_definitions: nil,
-        security: nil,
-        api_documentation: { desc: 'Swagger compatible API description' },
-        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
-        endpoint_auth_wrapper: nil,
-        swagger_endpoint_guard: nil,
-        token_owner: nil
-      }
-    end
-
     def class_variables_from(options)
       @@mount_path              = options[:mount_path]
       @@class_name              = options[:class_name] || options[:mount_path].delete('/')
       @@hide_documentation_path = options[:hide_documentation_path]
     end
 
-    def tags_from(paths, options)
-      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+    def setup_formatter(formatter)
+      return unless formatter
 
-      if options[:tags]
-        names = options[:tags].map { |t| t[:name] }
-        tags.reject! { |t| names.include?(t[:name]) }
-        tags += options[:tags]
-      end
-
-      tags
+      FORMATTER_METHOD.each { |method| send(method, formatter) }
     end
   end
 end

data/lib/grape-swagger/endpoint.rb

@@ -11,7 +11,7 @@ module Grape
 
       if content_types.empty?
         formats       = [target_class.format, target_class.default_format].compact.uniq
-        formats       = Grape::Formatter.formatters({}).keys if formats.empty?
+        formats       = Grape::Formatter.formatters(**{}).keys if formats.empty?
         content_types = Grape::ContentTypes::CONTENT_TYPES.select do |content_type, _mime_type|
           formats.include? content_type
         end.values
@@ -78,11 +78,11 @@ module Grape
     def path_and_definition_objects(namespace_routes, options)
       @paths = {}
       @definitions = {}
+      add_definitions_from options[:models]
       namespace_routes.each_value do |routes|
         path_item(routes, options)
       end
 
-      add_definitions_from options[:models]
       [@paths, @definitions]
     end
 
@@ -175,15 +175,18 @@ module Grape
     end
 
     def params_object(route, options, path)
-      parameters = partition_params(route, options).map do |param, value|
+      parameters = build_request_params(route, options).each_with_object([]) do |(param, value), memo|
+        next if hidden_parameter?(value)
+
         value = { required: false }.merge(value) if value.is_a?(Hash)
         _, value = default_type([[param, value]]).first if value == ''
+
         if value.dig(:documentation, :type)
           expose_params(value[:documentation][:type])
         elsif value[:type]
           expose_params(value[:type])
         end
-        GrapeSwagger::DocMethods::ParseParams.call(param, value, path, route, @definitions)
+        memo << GrapeSwagger::DocMethods::ParseParams.call(param, value, path, route, @definitions)
       end
 
       if GrapeSwagger::DocMethods::MoveParams.can_be_moved?(route.request_method, parameters)
@@ -196,35 +199,38 @@ module Grape
     end
 
     def response_object(route, options)
-      codes = http_codes_from_route(route)
-      codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3], headers: x[4] } : x }
-
-      codes.each_with_object({}) do |value, memo|
+      codes(route).each_with_object({}) do |value, memo|
         value[:message] ||= ''
-        memo[value[:code]] = { description: value[:message] }
-
+        memo[value[:code]] = { description: value[:message] ||= '' } unless memo[value[:code]].present?
         memo[value[:code]][:headers] = value[:headers] if value[:headers]
 
         next build_file_response(memo[value[:code]]) if file_response?(value[:model])
 
-        response_model = @item
-        response_model = expose_params_from_model(value[:model]) if value[:model]
-
         if memo.key?(200) && route.request_method == 'DELETE' && value[:model].nil?
           memo[204] = memo.delete(200)
           value[:code] = 204
+          next
         end
 
-        next if value[:code] == 204
-        next unless !response_model.start_with?('Swagger_doc') && (@definitions[response_model] || value[:model])
+        # Explicitly request no model with { model: '' }
+        next if value[:model] == ''
 
-        @definitions[response_model][:description] = description_object(route)
+        response_model = value[:model] ? expose_params_from_model(value[:model]) : @item
+        next unless @definitions[response_model]
+        next if response_model.start_with?('Swagger_doc')
 
-        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+        @definitions[response_model][:description] ||= "#{response_model} model"
+        build_memo_schema(memo, route, value, response_model, options)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
 
+    def codes(route)
+      http_codes_from_route(route).map do |x|
+        x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3], headers: x[4] } : x
+      end
+    end
+
     def success_code?(code)
       status = code.is_a?(Array) ? code.first : code[:code]
       status.between?(200, 299)
@@ -250,7 +256,7 @@ module Grape
 
     def tag_object(route, path)
       version = GrapeSwagger::DocMethods::Version.get(route)
-      version = [version] unless version.is_a?(Array)
+      version = Array(version)
       prefix = route.prefix.to_s.split('/').reject(&:empty?)
       Array(
         path.split('{')[0].split('/').reject(&:empty?).delete_if do |i|
@@ -261,15 +267,52 @@ module Grape
 
     private
 
+    def build_memo_schema(memo, route, value, response_model, options)
+      if memo[value[:code]][:schema] && value[:as]
+        memo[value[:code]][:schema][:properties].merge!(build_reference(route, value, response_model, options))
+
+        if value[:required]
+          memo[value[:code]][:schema][:required] ||= []
+          memo[value[:code]][:schema][:required] << value[:as].to_s
+        end
+
+      elsif value[:as]
+        memo[value[:code]][:schema] = {
+          type: :object,
+          properties: build_reference(route, value, response_model, options)
+        }
+        memo[value[:code]][:schema][:required] = [value[:as].to_s] if value[:required]
+      else
+        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+      end
+    end
+
     def build_reference(route, value, response_model, settings)
       # TODO: proof that the definition exist, if model isn't specified
-      reference = { '$ref' => "#/definitions/#{response_model}" }
+      reference = if value.key?(:as)
+                    { value[:as] => build_reference_hash(response_model) }
+                  else
+                    build_reference_hash(response_model)
+                  end
       return reference unless value[:code] < 300
 
-      reference = { type: 'array', items: reference } if route.options[:is_array]
+      if value.key?(:as) && value.key?(:is_array)
+        reference[value[:as]] = build_reference_array(reference[value[:as]])
+      elsif route.options[:is_array]
+        reference = build_reference_array(reference)
+      end
+
       build_root(route, reference, response_model, settings)
     end
 
+    def build_reference_hash(response_model)
+      { '$ref' => "#/definitions/#{response_model}" }
+    end
+
+    def build_reference_array(reference)
+      { type: 'array', items: reference }
+    end
+
     def build_root(route, reference, response_model, settings)
       default_root = response_model.underscore
       default_root = default_root.pluralize if route.options[:is_array]
@@ -286,23 +329,20 @@ module Grape
     end
 
     def file_response?(value)
-      value.to_s.casecmp('file').zero? ? true : false
+      value.to_s.casecmp('file').zero?
     end
 
     def build_file_response(memo)
       memo['schema'] = { type: 'file' }
     end
 
-    def partition_params(route, settings)
-      declared_params = route.settings[:declared_params] if route.settings[:declared_params].present?
+    def build_request_params(route, settings)
       required = merge_params(route)
       required = GrapeSwagger::DocMethods::Headers.parse(route) + required unless route.headers.nil?
 
       default_type(required)
 
-      request_params = unless declared_params.nil? && route.headers.nil?
-                         GrapeSwagger::Endpoint::ParamsParser.parse_request_params(required, settings, self)
-                       end || {}
+      request_params = GrapeSwagger::Endpoint::ParamsParser.parse_request_params(required, settings, self)
 
       request_params.empty? ? required : request_params
     end
@@ -340,12 +380,10 @@ module Grape
       parser = GrapeSwagger.model_parsers.find(model)
       raise GrapeSwagger::Errors::UnregisteredParser, "No parser registered for #{model_name}." unless parser
 
-      properties, required = parser.new(model, self).call
-      unless properties&.any?
-        raise GrapeSwagger::Errors::SwaggerSpec,
-              "Empty model #{model_name}, swagger 2.0 doesn't support empty definitions."
-      end
-      @definitions[model_name] = GrapeSwagger::DocMethods::BuildModelDefinition.build(model, properties, required)
+      parsed_response = parser.new(model, self).call
+
+      @definitions[model_name] =
+        GrapeSwagger::DocMethods::BuildModelDefinition.parse_params_from_model(parsed_response, model, model_name)
 
       model_name
     end
@@ -362,6 +400,16 @@ module Grape
       options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
     end
 
+    def hidden_parameter?(value)
+      return false if value[:required]
+
+      if value.dig(:documentation, :hidden).is_a?(Proc)
+        value.dig(:documentation, :hidden).call
+      else
+        value.dig(:documentation, :hidden)
+      end
+    end
+
     def success_code_from_entity(route, entity)
       default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
       if entity.is_a?(Hash)
@@ -370,6 +418,9 @@ module Grape
         default_code[:message] = entity[:message] || route.description || default_code[:message].sub('{item}', @item)
         default_code[:examples] = entity[:examples] if entity[:examples]
         default_code[:headers] = entity[:headers] if entity[:headers]
+        default_code[:as] = entity[:as] if entity[:as]
+        default_code[:is_array] = entity[:is_array] if entity[:is_array]
+        default_code[:required] = entity[:required] if entity[:required]
       else
         default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
         default_code[:model] = entity if entity

data/lib/grape-swagger/errors.rb

@@ -3,7 +3,9 @@
 module GrapeSwagger
   module Errors
     class UnregisteredParser < StandardError; end
+
     class SwaggerSpec < StandardError; end
+
     class SwaggerSpecDeprecated < SwaggerSpec
       class << self
         def tell!(what)