#215 - Adds example parameter to set swaggerDefault value without a Grape default

Author: dancostalis

.rubocop_todo.yml

@@ -1,36 +1,36 @@
 # This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-03-11 10:53:03 -0400 using RuboCop version 0.27.0.
+# on 2015-03-12 10:07:36 -0500 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: 10
 Metrics/AbcSize:
-  Max: 347
+  Max: 357
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 486
+  Max: 494
 
 # Offense count: 6
 Metrics/CyclomaticComplexity:
-  Max: 99
+  Max: 105
 
-# Offense count: 294
+# Offense count: 297
 # Configuration parameters: AllowURI, URISchemes.
 Metrics/LineLength:
   Max: 254
 
 # Offense count: 20
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 369
+  Max: 377
 
 # Offense count: 5
 Metrics/PerceivedComplexity:
-  Max: 101
+  Max: 107
 
 # Offense count: 8
 Style/ClassVars:

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### 0.10.2 (Next)
 
+* [#215](https://github.com/tim-vandecasteele/grape-swagger/pull/223): Support swagger `defaultValue` without the need to set a Grape `default` - [@jv-dan](https://github.com/jv-dan).
 * Your contribution here.
 
 ### 0.10.1 (March 11, 2015)

README.md

@@ -229,6 +229,28 @@ The name should not contain whitespaces or any other special characters due to f
       end
     end
 
+## Additional documentation
+
+## Setting a Swagger defaultValue
+
+Grape allows for an additional documentation hash to be passed to a parameter.
+
+    params do
+      requires :id, type: Integer, desc: 'Coffee ID'
+      requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { example: 72 }
+    end
+
+The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
+
+Grape uses the option `default` to set a default value for optional parameters. This is different in that Grape will set your parameter to the provided default if the parameter is omitted, whereas the example value above will only set the value in the UI itself. This will set the Swagger `defaultValue` to the provided value. Note that the example value will override the Grape default value.
+
+
+    params do
+      requires :id, type: Integer, desc: 'Coffee ID'
+      optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
+    end
+
+
 ## Grape Entities
 
 Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.

lib/grape-swagger.rb

@@ -200,9 +200,17 @@ def parse_params(params, path, method)
                                 else
                                   @@documentation_class.parse_entity_name(raw_data_type)
                                 end
+
+                additional_documentation = value.is_a?(Hash) ? value[:documentation] : nil
+
+                if additional_documentation && value.is_a?(Hash)
+                  value = additional_documentation.merge(value)
+                end
+
                 description   = value.is_a?(Hash) ? value[:desc] || value[:description] : ''
                 required      = value.is_a?(Hash) ? !!value[:required] : false
                 default_value = value.is_a?(Hash) ? value[:default] : nil
+                example       = value.is_a?(Hash) ? value[:example] : 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)
@@ -238,10 +246,14 @@ def parse_params(params, path, method)
                   required:      required,
                   allowMultiple: is_array
                 }
+
                 parsed_params.merge!(format: 'int32') if data_type == 'integer'
                 parsed_params.merge!(format: 'int64') if data_type == 'long'
                 parsed_params.merge!(items: items) if items.present?
-                parsed_params.merge!(defaultValue: default_value) if default_value
+                parsed_params.merge!(defaultValue: example) if example
+                if default_value && example.blank?
+                  parsed_params.merge!(defaultValue: default_value)
+                end
                 parsed_params.merge!(enum: enum_values) if enum_values
                 parsed_params
               end

spec/grape-swagger_helper_spec.rb

@@ -24,6 +24,19 @@ class HelperTestAPI < Grape::API
       ]
     end
 
+    it 'parses params as query strings for a GET with an example' do
+      params = {
+        name: { type: 'String', desc: 'A name', required: true, default: 'default api value', documentation: { example: 'default swagger value' } },
+        level: 'max'
+      }
+      path = '/coolness'
+      method = 'GET'
+      expect(subject.parse_params(params, path, method)).to eq [
+        { paramType: 'query', name: :name, description: 'A name', type: 'string', required: true, allowMultiple: false, defaultValue: 'default swagger value' },
+        { paramType: 'query', name: :level, description: '', type: 'string', required: false, allowMultiple: false }
+      ]
+    end
+
     it 'parses params as form for a POST' do
       params = {
         name: { type: 'String', desc: 'A name', required: true },