grape-swagger 0.33.0 → 0.34.0

data/README.md

@@ -104,9 +104,9 @@ Also added support for [representable](https://github.com/apotonick/representabl
 
 ```ruby
 # For Grape::Entity ( https://github.com/ruby-grape/grape-entity )
-gem 'grape-swagger-entity'
+gem 'grape-swagger-entity', '~> 0.3'
 # For representable ( https://github.com/apotonick/representable )
-gem 'grape-swagger-representable'
+gem 'grape-swagger-representable', '~> 0.2'
 ```
 
 If you are not using Rails, make sure to load the parser inside your application initialization logic, e.g., via `require 'grape-swagger/entity'` or `require 'grape-swagger/representable'`.
@@ -189,6 +189,7 @@ end
 * [base_path](#base_path)
 * [mount_path](#mount_path)
 * [add_base_path](#add_base_path)
+* [add_root](#add_root)
 * [add_version](#add_version)
 * [doc_version](#doc_version)
 * [endpoint_auth_wrapper](#endpoint_auth_wrapper)
@@ -248,6 +249,13 @@ add_swagger_documentation \
    add_base_path: true # only if base_path given
 ```
 
+#### add_root: <a name="add_root"></a>
+Add root element to all the responses, default is: `false`.
+```ruby
+add_swagger_documentation \
+   add_root: true
+```
+
 #### add_version: <a name="add_version"></a>
 
 Add `version` key to the documented path keys, default is: `true`,
@@ -447,6 +455,7 @@ add_swagger_documentation \
 * [Extensions](#extensions)
 * [Response examples documentation](#response-examples)
 * [Response headers documentation](#response-headers)
+* [Adding root element to responses](#response-root)
 
 #### Swagger Header Parameters  <a name="headers"></a>
 
@@ -913,7 +922,7 @@ desc 'Attach a field to an entity through a PUT',
     failure: [
       { code: 400, message: 'Bad request' },
       { code: 404, message: 'Not found' }
-    ]  
+    ]
 put do
   # your code comes here
 end
@@ -1180,6 +1189,60 @@ The result will look like following:
 
 Failure information can be passed as an array of arrays or an array of hashes.
 
+#### Adding root element to responses <a name="response-root"></a>
+
+You can specify a custom root element for a successful response:
+
+```ruby
+route_setting :swagger, root: 'cute_kitten'
+desc 'Get a kitten' do
+  http_codes [{ code: 200, model: Entities::Kitten }]
+end
+get '/kittens/:id' do
+end
+```
+
+The result will look like following:
+
+```
+  "responses": {
+    "200": {
+      "description": "Get a kitten",
+      "schema": {
+        "type": "object",
+        "properties": { "cute_kitten": { "$ref": "#/definitions/Kitten" } }
+      }
+    }
+  }
+```
+
+If you specify `true`, the value of the root element will be deduced based on the model name.
+E.g. in the following example the root element will be "kittens":
+
+```ruby
+route_setting :swagger, root: true
+desc 'Get kittens' do
+  is_array true
+  http_codes [{ code: 200, model: Entities::Kitten }]
+end
+get '/kittens' do
+end
+```
+
+The result will look like following:
+
+```
+  "responses": {
+    "200": {
+      "description": "Get kittens",
+      "schema": {
+        "type": "object",
+        "properties": { "type": "array", "items": { "kittens": { "$ref": "#/definitions/Kitten" } } }
+      }
+    }
+  }
+```
+
 ## Using Grape Entities <a name="grape-entity"></a>
 
 Add the [grape-entity](https://github.com/ruby-grape/grape-entity) and [grape-swagger-entity](https://github.com/ruby-grape/grape-swagger-entity) gem to your Gemfile.

data/grape-swagger.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
 
   s.required_ruby_version = '>= 2.4'
-  s.add_runtime_dependency 'grape', '>= 0.16.2'
+  s.add_runtime_dependency 'grape', '>= 0.16.2', '<= 1.2.5'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")

data/lib/grape-swagger.rb

@@ -26,7 +26,7 @@ module SwaggerRouting
   def combine_routes(app, doc_klass)
     app.routes.each do |route|
       route_path = route.path
-      route_match = route_path.split(/^.*?#{route.prefix.to_s}/).last
+      route_match = route_path.split(/^.*?#{route.prefix}/).last
       next unless route_match
 
       route_match = route_match.match('\/([\w|-]*?)[\.\/\(]') || route_match.match('\/([\w|-]*)$')

data/lib/grape-swagger/doc_methods.rb

@@ -4,6 +4,7 @@ require 'grape-swagger/doc_methods/status_codes'
 require 'grape-swagger/doc_methods/produces_consumes'
 require 'grape-swagger/doc_methods/data_type'
 require 'grape-swagger/doc_methods/extensions'
+require 'grape-swagger/doc_methods/format_data'
 require 'grape-swagger/doc_methods/operation_id'
 require 'grape-swagger/doc_methods/optional_object'
 require 'grape-swagger/doc_methods/path_string'
@@ -102,6 +103,7 @@ module GrapeSwagger
         base_path: nil,
         add_base_path: false,
         add_version: true,
+        add_root: false,
         hide_documentation_path: true,
         format: :json,
         authorizations: nil,

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

@@ -25,27 +25,10 @@ module GrapeSwagger
 
         def parse_entity(model)
           return unless model.respond_to?(:documentation)
-
-          deprecated_workflow_for('grape-swagger-entity')
-
-          model.documentation
-               .select { |_name, options| options[:required] }
-               .map { |name, options| options[:as] || name }
         end
 
         def parse_representable(model)
           return unless model.respond_to?(:map)
-
-          deprecated_workflow_for('grape-swagger-representable')
-
-          model.map
-               .select { |p| p[:documentation] && p[:documentation][:required] }
-               .map(&:name)
-        end
-
-        def deprecated_workflow_for(gem_name)
-          warn "DEPRECATED: You are using old #{gem_name} version, which doesn't provide " \
-            "required attributes. To solve this problem, please update #{gem_name}"
         end
       end
     end

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

@@ -87,7 +87,12 @@ module GrapeSwagger
           part.select { |x| x == identifier }
         end
 
-        def method
+        def method(*args)
+          # We're shadowing Object.method(:symbol) here so we provide
+          # a compatibility layer for code that introspects the methods
+          # of this class
+          return super if args.size.positive?
+
           @route.request_method.downcase.to_sym
         end
       end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class FormatData
+      class << self
+        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/, '') + '[')
+            end
+            parameters.reject! { |p| p[:name] == b[:name] } if move_down(b, related_parameters)
+          end
+          parameters
+        end
+
+        def move_down(parameter, related_parameters)
+          case parameter[:type]
+          when 'array'
+            add_array(parameter, related_parameters)
+            unless related_parameters.blank?
+              add_braces(parameter, related_parameters) if parameter[:name].match?(/\A.*\[\]\z/)
+              return true
+            end
+          when 'object'
+            return true
+          end
+          false
+        end
+
+        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 + '[]') }
+        end
+
+        def add_array(parameter, related_parameters)
+          related_parameters.each do |p|
+            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? }
+            p[:type] = 'array'
+            p[:is_array] = parameter[:is_array]
+            p.delete(:format)
+            p.delete(:enum)
+            p.delete_if { |_k, v| v.nil? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module GrapeSwagger
       class << self
         attr_accessor :definitions
 
-        def can_be_moved?(params, http_verb)
+        def can_be_moved?(http_verb, params)
           move_methods.include?(http_verb) && includes_body_param?(params)
         end
 
@@ -51,22 +51,33 @@ module GrapeSwagger
 
         def move_params_to_new(definition, params)
           params, nested_params = params.partition { |x| !x[:name].to_s.include?('[') }
-
-          unless params.blank?
-            properties, required = build_properties(params)
-            add_properties_to_definition(definition, properties, required)
+          params.each do |param|
+            property = param[:name]
+            param_properties, param_required = build_properties([param])
+            add_properties_to_definition(definition, param_properties, param_required)
+            related_nested_params, nested_params = nested_params.partition { |x| x[:name].start_with?("#{property}[") }
+            prepare_nested_names(property, related_nested_params)
+
+            next if related_nested_params.blank?
+
+            nested_definition = if should_expose_as_array?([param])
+                                  move_params_to_new(array_type, related_nested_params)
+                                else
+                                  move_params_to_new(object_type, related_nested_params)
+                                end
+            if definition.key?(:items)
+              definition[:items][:properties][property.to_sym].deep_merge!(nested_definition)
+            else
+              definition[:properties][property.to_sym].deep_merge!(nested_definition)
+            end
           end
-
-          nested_properties = build_nested_properties(nested_params) unless nested_params.blank?
-          add_properties_to_definition(definition, nested_properties, []) unless nested_params.blank?
+          definition
         end
 
         def build_properties(params)
           properties = {}
           required = []
 
-          prepare_nested_types(params) if should_expose_as_array?(params)
-
           params.each do |param|
             name = param[:name].to_sym
 
@@ -103,28 +114,6 @@ module GrapeSwagger
           end
         end
 
-        def build_nested_properties(params, properties = {})
-          property = params.bsearch { |x| x[:name].include?('[') }[:name].split('[').first
-
-          nested_params, params = params.partition { |x| x[:name].start_with?("#{property}[") }
-          prepare_nested_names(property, nested_params)
-
-          recursive_call(properties, property, nested_params) unless nested_params.empty?
-          build_nested_properties(params, properties) unless params.empty?
-
-          properties
-        end
-
-        def recursive_call(properties, property, nested_params)
-          if should_expose_as_array?(nested_params)
-            properties[property.to_sym] = array_type
-            move_params_to_new(properties[property.to_sym][:items], nested_params)
-          else
-            properties[property.to_sym] = object_type
-            move_params_to_new(properties[property.to_sym], nested_params)
-          end
-        end
-
         def movable_params(params)
           to_delete = params.each_with_object([]) { |x, memo| memo << x if deletable?(x) }
           delete_from(params, to_delete)
@@ -177,22 +166,6 @@ module GrapeSwagger
           { type: 'object', properties: {} }
         end
 
-        def prepare_nested_types(params)
-          params.each do |param|
-            next unless param[:items]
-
-            param[:type] = if param[:items][:type] == 'array'
-                             'string'
-                           elsif param[:items].key?('$ref')
-                             param[:type] = 'object'
-                           else
-                             param[:items][:type]
-                           end
-            param[:format] = param[:items][:format] if param[:items][:format]
-            param.delete(:items) if param[:type] != 'object'
-          end
-        end
-
         def prepare_nested_names(property, params)
           params.each { |x| x[:name] = x[:name].sub(property, '').sub('[', '').sub(']', '') }
         end
@@ -208,7 +181,7 @@ module GrapeSwagger
         end
 
         def property_keys
-          %i[type format description minimum maximum items enum default]
+          %i[type format description minimum maximum items enum default additionalProperties]
         end
 
         def deletable?(param)

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

@@ -25,6 +25,7 @@ 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)
 
           @parsed_param
         end
@@ -91,6 +92,11 @@ module GrapeSwagger
           @parsed_param[:collectionFormat] = collection_format if DataType.collections.include?(collection_format)
         end
 
+        def document_additional_properties(settings)
+          additional_properties = settings[:additionalProperties]
+          @parsed_param[:additionalProperties] = additional_properties if additional_properties
+        end
+
         def param_type(value_type)
           param_type = value_type[:param_type] || value_type[:in]
           if value_type[:path].include?("{#{value_type[:param_name]}}")

data/lib/grape-swagger/endpoint.rb

@@ -78,8 +78,7 @@ module Grape
     def path_and_definition_objects(namespace_routes, options)
       @paths = {}
       @definitions = {}
-      namespace_routes.each_key do |key|
-        routes = namespace_routes[key]
+      namespace_routes.each_value do |routes|
         path_item(routes, options)
       end
 
@@ -121,7 +120,7 @@ module Grape
       method[:consumes]    = consumes_object(route, options[:format])
       method[:parameters]  = params_object(route, options, path)
       method[:security]    = security_object(route)
-      method[:responses]   = response_object(route)
+      method[:responses]   = response_object(route, options)
       method[:tags]        = route.options.fetch(:tags, tag_object(route, path))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method[:deprecated] = deprecated_object(route)
@@ -179,22 +178,24 @@ module Grape
       parameters = partition_params(route, options).map do |param, value|
         value = { required: false }.merge(value) if value.is_a?(Hash)
         _, value = default_type([[param, value]]).first if value == ''
-        if value[:type]
-          expose_params(value[:type])
-        elsif value[:documentation]
+        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)
       end
 
-      if GrapeSwagger::DocMethods::MoveParams.can_be_moved?(parameters, route.request_method)
+      if GrapeSwagger::DocMethods::MoveParams.can_be_moved?(route.request_method, parameters)
         parameters = GrapeSwagger::DocMethods::MoveParams.to_definition(path, parameters, route, @definitions)
       end
 
+      GrapeSwagger::DocMethods::FormatData.to_format(parameters)
+
       parameters.presence
     end
 
-    def response_object(route)
+    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 }
 
@@ -219,7 +220,7 @@ module Grape
 
         @definitions[response_model][:description] = description_object(route)
 
-        memo[value[:code]][:schema] = build_reference(route, value, response_model)
+        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
@@ -250,20 +251,38 @@ module Grape
     def tag_object(route, path)
       version = GrapeSwagger::DocMethods::Version.get(route)
       version = [version] unless version.is_a?(Array)
-
+      prefix = route.prefix.to_s.split('/').reject(&:empty?)
       Array(
         path.split('{')[0].split('/').reject(&:empty?).delete_if do |i|
-          i == route.prefix.to_s || version.map(&:to_s).include?(i)
+          prefix.include?(i) || version.map(&:to_s).include?(i)
         end.first
       ).presence
     end
 
     private
 
-    def build_reference(route, value, response_model)
+    def build_reference(route, value, response_model, settings)
       # TODO: proof that the definition exist, if model isn't specified
       reference = { '$ref' => "#/definitions/#{response_model}" }
-      route.options[:is_array] && value[:code] < 300 ? { type: 'array', items: reference } : reference
+      return reference unless value[:code] < 300
+
+      reference = { type: 'array', items: reference } if route.options[:is_array]
+      build_root(route, reference, response_model, settings)
+    end
+
+    def build_root(route, reference, response_model, settings)
+      default_root = response_model.underscore
+      default_root = default_root.pluralize if route.options[:is_array]
+      case route.settings.dig(:swagger, :root)
+      when true
+        { type: 'object', properties: { default_root => reference } }
+      when false
+        reference
+      when nil
+        settings[:add_root] ? { type: 'object', properties: { default_root => reference } } : reference
+      else
+        { type: 'object', properties: { route.settings.dig(:swagger, :root) => reference } }
+      end
     end
 
     def file_response?(value)