Add support for property examples

cf. ruby-grape/grape-swagger-entity#28

Author: yewton

lib/grape-swagger/representable/parser.rb

@@ -42,6 +42,9 @@ def parse_representer_property(property)
           values = documentation[:values] || property[:values] || nil
           memo[:enum] = values if values.is_a?(Array)
 
+          example = documentation[:example] || property[:example] || nil
+          memo[:example] = example.is_a?(Proc) ? example.call : example if example
+
           if is_a_collection || documentation[:is_array]
             memo = {
               type: :array,

spec/grape-swagger/representers/response_inline_representer_spec.rb

@@ -7,13 +7,13 @@ module Representers
         class Kind < Representable::Decorator
           include Representable::JSON
 
-          property :id, documentation: { type: Integer, desc: 'Title of the kind.' }
+          property :id, documentation: { type: Integer, desc: 'Title of the kind.', example: 123 }
         end
 
         class Tag < Representable::Decorator
           include Representable::JSON
 
-          property :name, documentation: { type: 'string', desc: 'Name' }
+          property :name, documentation: { type: 'string', desc: 'Name', example: -> { 'A tag' } }
         end
 
         class Error < Representable::Decorator
@@ -125,7 +125,7 @@ def app
         'kind2' => {
           'type' => 'object',
           'properties' => {
-            'id' => { 'description' => 'Title of the kind.', 'type' => 'integer', 'format' => 'int32' },
+            'id' => { 'description' => 'Title of the kind.', 'type' => 'integer', 'format' => 'int32', 'example' => 123 },
             'name' => { 'description' => 'Kind name.', 'type' => 'string' }
           },
           'description' => 'Secondary kind.'
@@ -136,7 +136,7 @@ def app
           'items' => {
             'type' => 'object',
             'properties' => {
-              'name' => { 'description' => 'Name', 'type' => 'string' },
+              'name' => { 'description' => 'Name', 'type' => 'string', 'example' => 'A tag' },
               'color' => { 'description' => 'Tag color.', 'type' => 'string' }
             }
           },
@@ -147,7 +147,7 @@ def app
 
     expect(subject['definitions'].keys).to include 'Kind'
     expect(subject['definitions']['Kind']).to eq(
-      'type' => 'object', 'properties' => { 'id' => { 'description' => 'Title of the kind.', 'type' => 'integer', 'format' => 'int32' } }
+      'type' => 'object', 'properties' => { 'id' => { 'description' => 'Title of the kind.', 'type' => 'integer', 'format' => 'int32', 'example' => 123 } }
     )
   end
 end

spec/grape-swagger/representers/response_representer_spec.rb

@@ -7,13 +7,13 @@ module Representers
         class Kind < Representable::Decorator
           include Representable::JSON
 
-          property :title, documentation: { type: 'string', desc: 'Title of the kind.' }
+          property :title, documentation: { type: 'string', desc: 'Title of the kind.', example: 123 }
         end
 
         class Relation < Representable::Decorator
           include Representable::JSON
 
-          property :name, type: 'string', desc: 'RelationName', documentation: { type: 'string', desc: 'Name' }
+          property :name, type: 'string', desc: 'RelationName', documentation: { type: 'string', desc: 'Name', example: -> { 'A relation' } }
         end
 
         class Tag < Representable::Decorator
@@ -130,12 +130,12 @@ def app
 
     expect(subject['definitions'].keys).to include 'Kind'
     expect(subject['definitions']['Kind']).to eq(
-      'type' => 'object', 'properties' => { 'title' => { 'type' => 'string', 'description' => 'Title of the kind.' } }
+      'type' => 'object', 'properties' => { 'title' => { 'type' => 'string', 'description' => 'Title of the kind.', 'example' => 123 } }
     )
 
     expect(subject['definitions'].keys).to include 'Relation'
     expect(subject['definitions']['Relation']).to eq(
-      'type' => 'object', 'properties' => { 'name' => { 'type' => 'string', 'description' => 'Name' } }
+      'type' => 'object', 'properties' => { 'name' => { 'type' => 'string', 'description' => 'Name', 'example' => 'A relation' } }
     )
 
     expect(subject['definitions'].keys).to include 'Tag'