From 33366da965907ca0a97fda390b9530eb1cae7a8b Mon Sep 17 00:00:00 2001
From: Doug Hammond <d.lakehammond@gmail.com>
Date: Tue, 16 Mar 2021 11:40:00 +0100
Subject: [PATCH] Parameter examples (#821)

Co-authored-by: peter scholz <pscholz.le@gmail.com>
---
 README.md                                     | 13 +++++-
 lib/grape-swagger/doc_methods/parse_params.rb |  6 +++
 ...=> params_array_collection_format_spec.rb} |  0
 spec/swagger_v2/params_example_spec.rb        | 40 +++++++++++++++++++
 4 files changed, 57 insertions(+), 2 deletions(-)
 rename spec/swagger_v2/{params_array_collection_fromat_spec.rb => params_array_collection_format_spec.rb} (100%)
 create mode 100644 spec/swagger_v2/params_example_spec.rb

diff --git a/README.md b/README.md
index 802418c..d49faaa 100644
--- a/README.md
+++ b/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
 
diff --git a/lib/grape-swagger/doc_methods/parse_params.rb b/lib/grape-swagger/doc_methods/parse_params.rb
index 9cc70f0..3d3081c 100644
--- a/lib/grape-swagger/doc_methods/parse_params.rb
+++ b/lib/grape-swagger/doc_methods/parse_params.rb
@@ -27,6 +27,7 @@ module GrapeSwagger
           document_required(settings)
           document_additional_properties(settings)
           document_add_extensions(settings)
+          document_example(settings)
 
           @parsed_param
         end
@@ -112,6 +113,11 @@ module GrapeSwagger
           @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]}}")
diff --git a/spec/swagger_v2/params_array_collection_fromat_spec.rb b/spec/swagger_v2/params_array_collection_format_spec.rb
similarity index 100%
rename from spec/swagger_v2/params_array_collection_fromat_spec.rb
rename to spec/swagger_v2/params_array_collection_format_spec.rb
diff --git a/spec/swagger_v2/params_example_spec.rb b/spec/swagger_v2/params_example_spec.rb
new file mode 100644
index 0000000..86ee3d9
--- /dev/null
+++ b/spec/swagger_v2/params_example_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