Use x-example for non-body parameters

Author: olivier-thatch

lib/grape-swagger/doc_methods/parse_params.rb

@@ -141,8 +141,10 @@ def parse_additional_properties(definitions, settings)
         end
 
         def document_example(settings)
-          example = settings[:example]
-          @parsed_param[:example] = example if example
+          return unless settings.key?(:example)
+
+          key = @parsed_param[:in] == 'body' ? :example : :'x-example'
+          @parsed_param[key] = settings[:example]
         end
 
         def param_type(value_type, consumes)

spec/swagger_v2/params_example_spec.rb

@@ -7,13 +7,25 @@ def app
     Class.new(Grape::API) do
       format :json
 
+      helpers do
+        params :common_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
+      end
+
       params do
-        requires :id, type: Integer, documentation: { example: 123 }
-        optional :name, type: String, documentation: { example: 'Person' }
-        optional :obj, type: 'Object', documentation: { example: { 'foo' => 'bar' } }
+        use :common_params
+      end
+      get '/endpoint_with_examples/:id' do
+        { 'declared_params' => declared(params) }
       end
 
-      get '/endpoint_with_examples' do
+      params do
+        use :common_params
+      end
+      post '/endpoint_with_examples/:id' do
         { 'declared_params' => declared(params) }
       end
 
@@ -27,14 +39,34 @@ def app
       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 }
-        ]
-      )
+    describe 'examples for non-body parameters ' do
+      specify do
+        expect(subject['paths']['/endpoint_with_examples/{id}']['get']['parameters']).to eql(
+          [
+            { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'x-example' => 123, 'format' => 'int32', 'required' => true },
+            { 'in' => 'query', 'name' => 'name', 'type' => 'string', 'x-example' => 'Person', 'required' => false },
+            { 'in' => 'query', 'name' => 'obj', 'type' => 'Object', 'x-example' => { 'foo' => 'bar' }, 'required' => false }
+          ]
+        )
+      end
+    end
+
+    describe 'examples for body parameters' do
+      specify do
+        expect(subject['paths']['/endpoint_with_examples/{id}']['post']['parameters']).to eql(
+          [
+            { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'x-example' => 123, 'format' => 'int32', 'required' => true },
+            { 'in' => 'body', 'name' => 'postEndpointWithExamplesId', 'schema' => { '$ref' => '#/definitions/postEndpointWithExamplesId' }, 'required' => true }
+          ]
+        )
+        expect(subject['definitions']['postEndpointWithExamplesId']).to eql(
+          'type' => 'object',
+          'properties' => {
+            'name' => { 'type' => 'string', 'example' => 'Person' },
+            'obj' => { 'type' => 'Object', 'example' => { 'foo' => 'bar' } }
+          }
+        )
+      end
     end
   end
 end