grape-swagger 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 892c461e0945d50d3b923b7ee89f22aa1ab429f286f2f0fc4de76fe16098eb6f
-  data.tar.gz: 6c702b542c93dd5a3c0c459bd1135471bc112da3d1d7a48a882b0f2416542f22
+  metadata.gz: 8fbf69e7e7bc7f3a836c574fe91df74abb10aab05c778cee716398d76afeace6
+  data.tar.gz: 5ab4bc60eafa3ad32959a040aed645943121912037a738278d88fb649390a0fa
 SHA512:
-  metadata.gz: 66d718bc68a0e596eefb35d0cab1334754da8df8b3be13ba2114e0dac1930270d228c441d6fc8933aaef6379c7bee99d18a60e159aa747715e466922c5bca433
-  data.tar.gz: a380f3d1ac174ff023e2874e09d336f287bba09d6187e055477ee5d6841cedea2a910fa5f04ca38b3be848356d1a6cf085f9183e37b85a8b2cc8418b5e9616f0
+  metadata.gz: 8bcb10791418aa79af266d503f7fd5130157bb7971d7acb094964981d9ee8635fe6bcf72e212b81f22a25f2032a002fba99b97a7d078d8d35a908f0117fae379
+  data.tar.gz: d7843b9aaf70d83a9d0de3dc7f075b8f3df2e4cedda4a1c519cbc4109dc9da1cb1de82c9966fcf6a0083ebbe22a89c13654fbd9fe9e1156af4103e8bc70a344e

data/CHANGELOG.md

@@ -9,6 +9,27 @@
 * Your contribution here.
 
 
+### 2.1.0 (May 14, 2024)
+
+#### Features
+
+* [#927](https://github.com/ruby-grape/grape-swagger/pull/927): Set default parameter location based on consumes - [@spaceraccoon](https://github.com/spaceraccoon)
+* [#929](https://github.com/ruby-grape/grape-swagger/pull/929): Set query parameter for array of primitive types - [@spaceraccoon](https://github.com/spaceraccoon)
+
+#### Fixes
+
+* [#926](https://github.com/ruby-grape/grape-swagger/pull/926): Refactor route and namespace combination logic - [@numbata](https://github.com/numbata)
+
+
+### 2.0.3 (April 26, 2024)
+
+#### Fixes
+
+* [#922](https://github.com/ruby-grape/grape-swagger/pull/922): Force request body to be an schema object - [@numbata](https://github.com/numbata)
+* [#923](https://github.com/ruby-grape/grape-swagger/pull/923): Enabled schema definitions for body parameters in DELETE requests - [@numbata](https://github.com/numbata)
+* [#924](https://github.com/ruby-grape/grape-swagger/pull/924): fix: Use mount_path to narrow down urls_for - [@chibicco](https://github.com/chibicco)
+
+
 ### 2.0.2 (Februar 2, 2024)
 
 #### Fixes
@@ -72,7 +93,6 @@
 * [#846](https://github.com/ruby-grape/grape-swagger/pull/846): Refactor oapi fetch task [@Vachman](https://github.com/Vachman)
 * [#850](https://github.com/ruby-grape/grape-swagger/pull/850): Fix value of enum to be Array [@takahashim](https://github.com/takahashim)
 
-
 ### 1.4.3 (January 5, 2022)
 
 #### Fixes

data/UPGRADING.md

@@ -1,5 +1,14 @@
 ## Upgrading Grape-swagger
 
+### Upgrading to >= x.y.z
+
+- Grape-swagger now documents array parameters within an object schema in Swagger. This aligns with grape's JSON structure requirements and ensures the documentation is correct.
+  - Previously, arrays were documented as standalone arrays, which could be incorrect based on grape's expectations.
+  - Check your API documentation and update your code or tests that use the old array format.
+
+  Attention: This update may require you to make changes to ensure your API integrations continue to work correctly.
+  For detailed reasons behind this update, refer to GitHub issue #666.
+
 ### Upgrading to >= 1.5.0
 
 - The names generated for body parameter definitions and their references has changed. It'll now include the HTTP action as well as any path parameters.

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

@@ -75,6 +75,14 @@ module GrapeSwagger
           PRIMITIVE_MAPPINGS.keys.map(&:downcase)
         end
 
+        def query_array_primitive?(type)
+          query_array_primitives.include?(type.to_s.downcase)
+        end
+
+        def query_array_primitives
+          primitives << 'string'
+        end
+
         def mapping(value)
           PRIMITIVE_MAPPINGS[value] || 'string'
         end

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

@@ -18,8 +18,6 @@ module GrapeSwagger
 
           params_to_move = movable_params(params)
 
-          return (params + correct_array_param(params_to_move)) if should_correct_array?(params_to_move)
-
           params << parent_definition_of_params(params_to_move, path, route)
 
           params
@@ -27,21 +25,11 @@ module GrapeSwagger
 
         private
 
-        def should_correct_array?(param)
-          param.length == 1 && param.first[:in] == 'body' && param.first[:type] == 'array'
-        end
-
-        def correct_array_param(param)
-          param.first[:schema] = { type: param.first.delete(:type), items: param.first.delete(:items) }
-
-          param
-        end
-
         def parent_definition_of_params(params, path, route)
           definition_name = OperationId.build(route, path)
-          build_definition(definition_name, params)
+          # NOTE: Parent definition is always object
+          @definitions[definition_name] = object_type
           definition = @definitions[definition_name]
-
           move_params_to_new(definition, params)
 
           definition[:description] = route.description if route.try(:description)
@@ -53,6 +41,7 @@ module GrapeSwagger
           params, nested_params = params.partition { |x| !x[:name].to_s.include?('[') }
           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}[") }
@@ -197,7 +186,7 @@ module GrapeSwagger
         end
 
         def move_methods
-          [:post, :put, :patch, 'POST', 'PUT', 'PATCH']
+          [:delete, :post, :put, :patch, 'DELETE', 'POST', 'PUT', 'PATCH']
         end
 
         def includes_body_param?(params)

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

@@ -4,7 +4,7 @@ module GrapeSwagger
   module DocMethods
     class ParseParams
       class << self
-        def call(param, settings, path, route, definitions)
+        def call(param, settings, path, route, definitions, consumes) # rubocop:disable Metrics/ParameterLists
           method = route.request_method
           additional_documentation = settings.fetch(:documentation, {})
           settings.merge!(additional_documentation)
@@ -14,7 +14,7 @@ module GrapeSwagger
 
           # required properties
           @parsed_param = {
-            in: param_type(value_type),
+            in: param_type(value_type, consumes),
             name: settings[:full_name] || param
           }
 
@@ -70,21 +70,17 @@ module GrapeSwagger
 
         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 = DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
             collection_format = value_type[:documentation][:collectionFormat]
           end
 
-          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)
@@ -148,14 +144,20 @@ module GrapeSwagger
           @parsed_param[:example] = example if example
         end
 
-        def param_type(value_type)
+        def param_type(value_type, consumes)
           param_type = value_type[:param_type] || value_type[:in]
-          if value_type[:path].include?("{#{value_type[:param_name]}}")
+          if !value_type[:is_array] && value_type[:path].include?("{#{value_type[:param_name]}}")
             'path'
           elsif param_type
             param_type
           elsif %w[POST PUT PATCH].include?(value_type[:method])
-            DataType.request_primitive?(value_type[:data_type]) ? 'formData' : 'body'
+            if consumes.include?('application/x-www-form-urlencoded') || consumes.include?('multipart/form-data')
+              'formData'
+            else
+              'body'
+            end
+          elsif value_type[:is_array] && !DataType.query_array_primitive?(value_type[:data_type])
+            'formData'
           else
             'query'
           end

data/lib/grape-swagger/endpoint.rb

@@ -119,7 +119,7 @@ module Grape
       method[:description] = description_object(route)
       method[:produces]    = produces_object(route, options[:produces] || options[:format])
       method[:consumes]    = consumes_object(route, options[:consumes] || options[:format])
-      method[:parameters]  = params_object(route, options, path)
+      method[:parameters]  = params_object(route, options, path, method[:consumes])
       method[:security]    = security_object(route)
       method[:responses]   = response_object(route, options)
       method[:tags]        = route.options.fetch(:tags, tag_object(route, path))
@@ -175,7 +175,7 @@ module Grape
       GrapeSwagger::DocMethods::ProducesConsumes.call(route.settings.dig(:description, :consumes) || format)
     end
 
-    def params_object(route, options, path)
+    def params_object(route, options, path, consumes)
       parameters = build_request_params(route, options).each_with_object([]) do |(param, value), memo|
         next if hidden_parameter?(value)
 
@@ -187,7 +187,7 @@ module Grape
         elsif value[:type]
           expose_params(value[:type])
         end
-        memo << GrapeSwagger::DocMethods::ParseParams.call(param, value, path, route, @definitions)
+        memo << GrapeSwagger::DocMethods::ParseParams.call(param, value, path, route, @definitions, consumes)
       end
 
       if GrapeSwagger::DocMethods::MoveParams.can_be_moved?(route.request_method, parameters)

data/lib/grape-swagger/rake/oapi_tasks.rb

@@ -63,7 +63,7 @@ module GrapeSwagger
           resource - if given only for that it would be generated (optional)'
         task validate: :environment do
           # :nocov:
-          ENV['store'] = 'true'
+          ENV.store('store', 'true')
           ::Rake::Task['oapi:fetch'].invoke
           exit if error?
 
@@ -95,7 +95,7 @@ module GrapeSwagger
       def urls_for(api_class)
         api_class.routes
                  .map(&:path)
-                 .select { |e| e.include?('doc') }
+                 .grep(/#{GrapeSwagger::DocMethods.class_variable_get(:@@mount_path)}/)
                  .reject { |e| e.include?(':name') }
                  .map { |e| format_path(e) }
                  .map { |e| [e, ENV.fetch('resource', nil)].join('/').chomp('/') }
@@ -108,7 +108,7 @@ module GrapeSwagger
       end
 
       def save_to_file?
-        ENV['store'].present? && !error?
+        ENV.fetch('store', nil).present? && !error?
       end
 
       def error?
@@ -118,10 +118,10 @@ module GrapeSwagger
       def file(url)
         api_version = url.split('/').last
 
-        name = if ENV['store'] == 'true' || ENV['store'].blank?
+        name = if ENV.fetch('store', nil) == 'true' || ENV.fetch('store', nil).blank?
                  "swagger_doc_#{api_version}.json"
                else
-                 ENV['store'].sub('.json', "_#{api_version}.json")
+                 ENV.fetch('store').sub('.json', "_#{api_version}.json")
                end
 
         File.join(Dir.getwd, name)

data/lib/grape-swagger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeSwagger
-  VERSION = '2.0.2'
+  VERSION = '2.1.0'
 end

data/lib/grape-swagger.rb

@@ -24,7 +24,7 @@ module SwaggerRouting
   private
 
   def combine_routes(app, doc_klass)
-    app.routes.each do |route|
+    app.routes.each_with_object({}) do |route, combined_routes|
       route_path = route.path
       route_match = route_path.split(/^.*?#{route.prefix}/).last
       next unless route_match
@@ -37,16 +37,16 @@ module SwaggerRouting
 
       resource = route_match.captures.first
       resource = '/' if resource.empty?
-      @target_class.combined_routes[resource] ||= []
+      combined_routes[resource] ||= []
       next if doc_klass.hide_documentation_path && route.path.match(/#{doc_klass.mount_path}($|\/|\(\.)/)
 
-      @target_class.combined_routes[resource].unshift route
+      combined_routes[resource] << route
     end
   end
 
-  def determine_namespaced_routes(name, parent_route)
+  def determine_namespaced_routes(name, parent_route, routes)
     if parent_route.nil?
-      @target_class.combined_routes.values.flatten
+      routes.values.flatten
     else
       parent_route.reject do |route|
         !route_path_start_with?(route, name) || !route_instance_variable_equals?(route, name)
@@ -54,14 +54,15 @@ module SwaggerRouting
     end
   end
 
-  def combine_namespace_routes(namespaces)
+  def combine_namespace_routes(namespaces, routes)
+    combined_namespace_routes = {}
     # iterate over each single namespace
     namespaces.each_key do |name, _|
       # get the parent route for the namespace
       parent_route_name = extract_parent_route(name)
-      parent_route = @target_class.combined_routes[parent_route_name]
+      parent_route = routes[parent_route_name]
       # fetch all routes that are within the current namespace
-      namespace_routes = determine_namespaced_routes(name, parent_route)
+      namespace_routes = determine_namespaced_routes(name, parent_route, routes)
 
       # default case when not explicitly specified or nested == true
       standalone_namespaces = namespaces.reject do |_, ns|
@@ -76,12 +77,13 @@ module SwaggerRouting
       # rubocop:disable Style/Next
       if parent_standalone_namespaces.empty?
         # default option, append namespace methods to parent route
-        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)
+        combined_namespace_routes[parent_route_name] ||= []
+        combined_namespace_routes[parent_route_name].push(*namespace_routes)
       end
       # rubocop:enable Style/Next
     end
+
+    combined_namespace_routes
   end
 
   def extract_parent_route(name)
@@ -110,7 +112,7 @@ module SwaggerRouting
 end
 
 module SwaggerDocumentationAdder
-  attr_accessor :combined_namespaces, :combined_namespace_identifiers, :combined_routes, :combined_namespace_routes
+  attr_accessor :combined_namespaces, :combined_routes, :combined_namespace_routes
 
   include SwaggerRouting
 
@@ -127,20 +129,16 @@ module SwaggerDocumentationAdder
     documentation_class.setup(options)
     mount(documentation_class)
 
-    @target_class.combined_routes = {}
-    combine_routes(@target_class, documentation_class)
-
-    @target_class.combined_namespaces = {}
-    combine_namespaces(@target_class)
+    combined_routes = combine_routes(@target_class, documentation_class)
+    combined_namespaces = combine_namespaces(@target_class)
+    combined_namespace_routes = combine_namespace_routes(combined_namespaces, combined_routes)
+    exclusive_route_keys = combined_routes.keys - combined_namespaces.keys
+    @target_class.combined_namespace_routes = combined_namespace_routes.merge(
+      combined_routes.slice(*exclusive_route_keys)
+    )
+    @target_class.combined_routes = combined_routes
+    @target_class.combined_namespaces = combined_namespaces
 
-    @target_class.combined_namespace_routes = {}
-    @target_class.combined_namespace_identifiers = {}
-    combine_namespace_routes(@target_class.combined_namespaces)
-
-    exclusive_route_keys = @target_class.combined_routes.keys - @target_class.combined_namespaces.keys
-    exclusive_route_keys.each do |key|
-      @target_class.combined_namespace_routes[key] = @target_class.combined_routes[key]
-    end
     documentation_class
   end
 
@@ -151,17 +149,24 @@ module SwaggerDocumentationAdder
   end
 
   def combine_namespaces(app)
-    app.endpoints.each do |endpoint|
+    combined_namespaces = {}
+    endpoints = app.endpoints.clone
+
+    while endpoints.any?
+      endpoint = endpoints.shift
+
+      endpoints.push(*endpoint.options[:app].endpoints) if endpoint.options[:app]
       ns = endpoint.namespace_stackable(:namespace).last
+      next unless ns
 
       # use the full namespace here (not the latest level only)
       # and strip leading slash
       mount_path = (endpoint.namespace_stackable(:mount_path) || []).join('/')
       full_namespace = (mount_path + endpoint.namespace).sub(/\/{2,}/, '/').sub(/^\//, '')
-      @target_class.combined_namespaces[full_namespace] = ns if ns
-
-      combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
+      combined_namespaces[full_namespace] = ns
     end
+
+    combined_namespaces
   end
 
   def create_documentation_class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - LeFnord
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-02 00:00:00.000000000 Z
+date: 2024-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Add auto generated documentation to your Grape API that can be displayed