Parameter examples (#821)

Co-authored-by: peter scholz <pscholz.le@gmail.com>

Author: dslh

README.md

@@ -451,6 +451,7 @@ add_swagger_documentation \
 * [Collection Format](#collection-format)
 * [Hiding parameters](#hiding-parameters)
 * [Setting a Swagger default value](#default-value)
+* [Example parameter value](#param-example)
 * [Response documentation](#response)
 * [Changing default status codes](#change-status)
 * [File response](#file-response)
@@ -769,8 +770,6 @@ params do
 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.
 
 ```ruby
@@ -780,6 +779,16 @@ params do
 end
 ```
 
+#### Example parameter value <a name="param-example"></a>
+
+The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
+
+```ruby
+params do
+  requires :id, type: Integer, documentation: { example: 123 }
+  optional :name, type String, documentation: { example: 'Buddy Guy' }
+end
+```
 
 #### Expose nested namespace as standalone route
 

lib/grape-swagger/doc_methods/parse_params.rb

@@ -27,6 +27,7 @@ def call(param, settings, path, route, definitions)
           document_required(settings)
           document_additional_properties(settings)
           document_add_extensions(settings)
+          document_example(settings)
 
           @parsed_param
         end
@@ -112,6 +113,11 @@ def document_additional_properties(settings)
           @parsed_param[:additionalProperties] = additional_properties if additional_properties
         end
 
+        def document_example(settings)
+          example = settings[:example]
+          @parsed_param[:example] = example if example
+        end
+
         def param_type(value_type)
           param_type = value_type[:param_type] || value_type[:in]
           if value_type[:path].include?("{#{value_type[:param_name]}}")

spec/swagger_v2/params_array_collection_fromat_spec.rb renamed to spec/swagger_v2/params_array_collection_format_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Param example' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        requires :id, type: Integer, documentation: { example: 123 }
+        optional :name, type: String, documentation: { example: 'Person' }
+        optional :obj, type: 'Object', documentation: { example: { 'foo' => 'bar' } }
+      end
+
+      get '/endpoint_with_examples' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  describe 'documentation with parameter examples' do
+    subject do
+      get '/swagger_doc/endpoint_with_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/endpoint_with_examples']['get']['parameters']).to eql(
+        [
+          { 'in' => 'query', 'name' => 'id', 'type' => 'integer', 'example' => 123, 'format' => 'int32', 'required' => true },
+          { 'in' => 'query', 'name' => 'name', 'type' => 'string', 'example' => 'Person', 'required' => false },
+          { 'in' => 'query', 'name' => 'obj', 'type' => 'Object', 'example' => { 'foo' => 'bar' }, 'required' => false }
+        ]
+      )
+    end
+  end
+end