support property example (Apipie#901)

* support property example

[WHY]
* the generated swagger json didn't include the example for the response

[HOW]
* add a new option for params description `ex` to provided example for the specific parameters

* be explicit

Co-authored-by: Panos Dalitsouris <22100396+PanosCodes@users.noreply.github.com>

* Update lib/apipie/generator/swagger/param_description/builder.rb

Co-authored-by: Panos Dalitsouris <22100396+PanosCodes@users.noreply.github.com>

* rename key name from ex to example

* update readme for example option

* fix rubocop issues

---------

Co-authored-by: Mathieu Jobin <99191+mathieujobin@users.noreply.github.com>
Co-authored-by: Panos Dalitsouris <22100396+PanosCodes@users.noreply.github.com>

README.rst

@@ -317,6 +317,9 @@ desc
 required
   Set this true/false to make it required/optional. Default is optional
 
+example
+  Provide the example for this parameter.
+
 allow_nil
   Setting this to true means that ``nil`` can be passed.
 
@@ -349,8 +352,8 @@ Example:
 .. code:: ruby
 
    param :user, Hash, :desc => "User info" do
-     param :username, String, :desc => "Username for login", :required => true
-     param :password, String, :desc => "Password for login", :required => true
+     param :username, String, :desc => "Username for login", :required => true, :example => 'John'
+     param :password, String, :desc => "Password for login", :required => true, :example => '1234567'
      param :membership, ["standard","premium"], :desc => "User membership"
      param :admin_override, String, :desc => "Not shown in documentation", :show => false
      param :ip_address, String, :desc => "IP address", :required => true, :missing_message => lambda { I18n.t("ip_address.required") }

lib/apipie/generator/swagger/param_description/builder.rb

@@ -53,6 +53,7 @@ def to_swagger
 
     definition.merge!(for_default)
     definition.merge!(for_required)
+    definition.merge!(for_example)
     definition.merge!(@description.to_hash) if @description.present?
 
     warn_optional_without_default_value(definition)
@@ -78,6 +79,14 @@ def for_default
     }
   end
 
+  def for_example
+    return {} unless @param_description.options.key?(:example)
+
+    {
+      example: @param_description.options[:example],
+    }
+  end
+
   def required?
     required_from_path? || @param_description.required
   end

spec/dummy/app/controllers/pets_controller.rb

@@ -23,7 +23,7 @@ class PetsController < ApplicationController
   #-----------------------------------------------------------
   api :GET, "/pets/:id/as_properties", "Get a pet record"
   returns :code => 200 do
-    property :pet_name, String, :desc => "Name of pet", :required => false
+    property :pet_name, String, :desc => "Name of pet", :required => false, :example => 'mypet'
     property :animal_type, %w[dog cat iguana kangaroo], :desc => "Type of pet"   # required by default, because this is a 'property'
   end
   returns :code => 404 do

spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb

@@ -19,8 +19,8 @@
 
   let(:response_description_dsl) do
     proc do
-      property :a_number, Integer
-      property :an_optional_number, Integer, required: false
+      property :a_number, Integer, example: 1
+      property :an_optional_number, Integer, required: false, example: 2
     end
   end
 
@@ -56,10 +56,10 @@
         expect(properties).to eq(
           {
             a_number: {
-              type: 'number', required: true
+              type: 'number', required: true, example: 1
             },
             an_optional_number: {
-              type: 'number'
+              type: 'number', example: 2
             }
           }
         )
@@ -72,10 +72,10 @@
           expect(properties).to eq(
             {
               a_number: {
-                type: %w[number null], required: true
+                type: %w[number null], required: true, example: 1
               },
               an_optional_number: {
-                type: %w[number null]
+                type: %w[number null], example: 2
               }
             }
           )

spec/lib/apipie/generator/swagger/param_description/builder_spec.rb

@@ -200,4 +200,16 @@
       it { is_expected.to be_present }
     end
   end
+
+  describe 'example' do
+    subject { generated_block[:example] }
+
+    it { is_expected.to be_blank }
+
+    context 'when example is assigned' do
+      let(:base_param_description_options) { { example: 'example' } }
+
+      it { is_expected.to eq('example') }
+    end
+  end
 end

spec/lib/apipie/swagger_generator_spec.rb

@@ -7,7 +7,7 @@
 
     let(:response_description_dsl) do
       proc do
-        property :a_number, Integer
+        property :a_number, Integer, example: 1
         property :an_optional_number, Integer, required: false
       end
     end
@@ -61,7 +61,7 @@
           expect(properties).to eq(
             {
               a_number: {
-                type: 'number', required: true
+                type: 'number', required: true, example: 1
               },
               an_optional_number: {
                 type: 'number'

spec/lib/swagger/rake_swagger_spec.rb

@@ -82,6 +82,10 @@ def expect_body_param_def(http_method, path, param_name, field, value)
       expect(param[field]).to eq(value)
     end
 
+    def expect_response_params_def(http_method, path, response_code, param_name, field, value)
+      param = apidoc_swagger["paths"][path][http_method]["responses"][response_code.to_s]["schema"]["properties"][param_name]
+      expect(param[field]).to eq(value)
+    end
 
     describe 'apipie:static_swagger_json[development,json,_tmp]' do
       it "generates static swagger files for the default version of apipie docs" do
@@ -105,6 +109,7 @@ def expect_body_param_def(http_method, path, param_name, field, value)
                          %w[finance operations sales marketing HR])
 
         expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
+        expect_response_params_def("get", "/pets/{id}/as_properties", 200, "pet_name", "example", "mypet")
       end
 
       it "generates a valid swagger file" do