diff --git a/modules/swagger-codegen/src/main/resources/ruby/api.mustache b/modules/swagger-codegen/src/main/resources/ruby/api.mustache
index c045a46f69c..7bdb4764e29 100644
--- a/modules/swagger-codegen/src/main/resources/ruby/api.mustache
+++ b/modules/swagger-codegen/src/main/resources/ruby/api.mustache
@@ -9,12 +9,17 @@ class {{classname}}
     URI.encode(string.to_s)
   end
 
-  {{#operation}}
+{{#operation}}
+{{newline}}
+  # {{summary}}
+  # {{notes}}{{newLine}}
+{{#allParams}}{{^optional}}{{newLine}}  # @param {{paramName}} {{description}}
+{{/optional}}{{/allParams}}{{#allParams}}{{#optional}}{{newLine}}  # @option opts [{{dataType}}] :{{baseName}} {{description}}
+{{/optional}}{{/allParams}}  # @return {{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}void{{/returnType}}{{newLine}}
   def self.{{nickname}} ({{#allParams}}{{paramName}}{{#defaultValue}} = {{{defaultValue}}}{{/defaultValue}},{{/allParams}} opts={})
     query_param_keys = [{{#queryParams}}:{{paramName}}{{#hasMore}},{{/hasMore}}{{/queryParams}}]
 
     {{#requiredParamCount}}
-    
     # verify existence of params
     {{#requiredParams}}
     raise "{{{paramName}}} is required" if {{{paramName}}}.nil?
@@ -40,7 +45,6 @@ class {{classname}}
     headers = {}
     {{#headerParams}}{{#optional}}headers[:'{{{baseName}}}'] = options[:'{{{paramName}}}'] if options[:'{{{paramName}}}']{{/optional}}{{/headerParams}}
     {{#headerParams}}{{^optional}}headers[:'{{{baseName}}}'] = {{{paramName}}}{{/optional}}{{/headerParams}}
-
     # http body (model)
     post_body = nil
     {{#bodyParam}}
@@ -55,7 +59,6 @@ class {{classname}}
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -65,12 +68,10 @@ class {{classname}}
       end
     end
     {{/bodyParam}}
-
     # form parameters
     form_parameter_hash = {}
     {{#formParams}}{{#optional}}form_parameter_hash["{{baseName}}"] = options[:'{{paramName}}'] if options[:'{{paramName}}']{{/optional}}
     {{^optional}}form_parameter_hash["{{baseName}}"] = {{paramName}}{{/optional}}{{/formParams}}
-
     {{#returnType}}
     response = Swagger::Request.new(:{{httpMethod}}, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
     {{#returnContainer}}
@@ -81,7 +82,6 @@ class {{classname}}
     {{/returnType}}
   {{newline}}
   end
-
 {{/operation}}
 end
 {{/operations}}
diff --git a/samples/client/petstore/ruby/lib/pet_api.rb b/samples/client/petstore/ruby/lib/pet_api.rb
index e8b9644453c..072bc0d0cff 100644
--- a/samples/client/petstore/ruby/lib/pet_api.rb
+++ b/samples/client/petstore/ruby/lib/pet_api.rb
@@ -8,7 +8,11 @@ class PetApi
     URI.encode(string.to_s)
   end
 
-  
+
+  # Update an existing pet
+  # 
+  # @param body Pet object that needs to be added to the store
+  # @return void
   def self.updatePet (body, opts={})
     query_param_keys = []
 
@@ -32,7 +36,6 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -47,7 +50,6 @@ class PetApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -57,11 +59,9 @@ class PetApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:PUT, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -69,7 +69,10 @@ class PetApi
   
   end
 
-
+  # Add a new pet to the store
+  # 
+  # @param body Pet object that needs to be added to the store
+  # @return void
   def self.addPet (body, opts={})
     query_param_keys = []
 
@@ -93,7 +96,6 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -108,7 +110,6 @@ class PetApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -118,11 +119,9 @@ class PetApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -130,7 +129,10 @@ class PetApi
   
   end
 
-
+  # Finds Pets by status
+  # Multiple status values can be provided with comma seperated strings
+  # @param status Status values that need to be considered for filter
+  # @return array[Pet]
   def self.findPetsByStatus (status, opts={})
     query_param_keys = [:status]
 
@@ -154,15 +156,12 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
     
@@ -172,7 +171,10 @@ class PetApi
   
   end
 
-
+  # Finds Pets by tags
+  # Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
+  # @param tags Tags to filter by
+  # @return array[Pet]
   def self.findPetsByTags (tags, opts={})
     query_param_keys = [:tags]
 
@@ -196,15 +198,12 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
     
@@ -214,7 +213,10 @@ class PetApi
   
   end
 
-
+  # Find pet by ID
+  # Returns a pet when ID < 10.  ID > 10 or nonintegers will simulate API error conditions
+  # @param pet_id ID of pet that needs to be fetched
+  # @return Pet
   def self.getPetById (pet_id, opts={})
     query_param_keys = []
 
@@ -239,15 +241,12 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
      Pet.new(response)
@@ -256,7 +255,12 @@ class PetApi
   
   end
 
-
+  # Updates a pet in the store with form data
+  # 
+  # @param pet_id ID of pet that needs to be updated
+  # @param name Updated name of the pet
+  # @param status Updated status of the pet
+  # @return void
   def self.updatePetWithForm (pet_id,name,status, opts={})
     query_param_keys = []
 
@@ -283,17 +287,14 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
     form_parameter_hash["name"] = name
     form_parameter_hash["status"] = status
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -301,7 +302,11 @@ class PetApi
   
   end
 
-
+  # Deletes a pet
+  # 
+  # @param api_key 
+  # @param pet_id Pet id to delete
+  # @return void
   def self.deletePet (api_key,pet_id, opts={})
     query_param_keys = []
 
@@ -327,15 +332,12 @@ class PetApi
     headers = {}
     
     headers[:'api_key'] = api_key
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:DELETE, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -343,7 +345,12 @@ class PetApi
   
   end
 
-
+  # uploads an image
+  # 
+  # @param pet_id ID of pet to update
+  # @param additional_metadata Additional data to pass to server
+  # @param file file to upload
+  # @return void
   def self.uploadFile (pet_id,additional_metadata,file, opts={})
     query_param_keys = []
 
@@ -370,22 +377,18 @@ class PetApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
     form_parameter_hash["additionalMetadata"] = additional_metadata
     form_parameter_hash["file"] = file
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
     
   
   end
-
 end
diff --git a/samples/client/petstore/ruby/lib/store_api.rb b/samples/client/petstore/ruby/lib/store_api.rb
new file mode 100644
index 00000000000..c0796debeb7
--- /dev/null
+++ b/samples/client/petstore/ruby/lib/store_api.rb
@@ -0,0 +1,195 @@
+require "uri"
+
+class StoreApi
+  basePath = "http://petstore.swagger.io/v2"
+  # apiInvoker = APIInvoker
+
+  def self.escapeString(string)
+    URI.encode(string.to_s)
+  end
+
+
+  # Returns pet inventories by status
+  # Returns a map of status codes to quantities
+  # @return map[string,int]
+  def self.getInventory ( opts={})
+    query_param_keys = []
+
+    
+    
+    # set default values and merge with input
+    options = {
+      
+    }.merge(opts)
+
+    #resource path
+    path = "/store/inventory".sub('{format}','json')
+    
+    # pull querystring keys from options
+    queryopts = options.select do |key,value|
+      query_param_keys.include? key
+    end
+
+    # header parameters, if any
+    headers = {}
+    
+    
+    # http body (model)
+    post_body = nil
+    
+    # form parameters
+    form_parameter_hash = {}
+    
+    
+    response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
+    
+    response.map {|response| map.new(response) }
+    
+    
+  
+  end
+
+  # Place an order for a pet
+  # 
+  # @param body order placed for purchasing the pet
+  # @return Order
+  def self.placeOrder (body, opts={})
+    query_param_keys = []
+
+    
+    
+    # set default values and merge with input
+    options = {
+      :'body' => body
+      
+    }.merge(opts)
+
+    #resource path
+    path = "/store/order".sub('{format}','json')
+    
+    # pull querystring keys from options
+    queryopts = options.select do |key,value|
+      query_param_keys.include? key
+    end
+
+    # header parameters, if any
+    headers = {}
+    
+    
+    # http body (model)
+    post_body = nil
+    
+    if body != nil
+      if body.is_a?(Array)
+        array = Array.new
+        body.each do |item|
+          if item.respond_to?("to_body".to_sym)
+            array.push item.to_body
+          else
+            array.push item
+          end
+        end
+        post_body = array
+      else 
+        if body.respond_to?("to_body".to_sym)
+	        post_body = body.to_body
+	      else
+	        post_body = body
+	      end
+      end
+    end
+    
+    # form parameters
+    form_parameter_hash = {}
+    
+    
+    response = Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
+     Order.new(response)
+    
+    
+  
+  end
+
+  # Find purchase order by ID
+  # For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions
+  # @param order_id ID of pet that needs to be fetched
+  # @return Order
+  def self.getOrderById (order_id, opts={})
+    query_param_keys = []
+
+    
+    
+    # set default values and merge with input
+    options = {
+      :'order_id' => order_id
+      
+    }.merge(opts)
+
+    #resource path
+    path = "/store/order/{orderId}".sub('{format}','json').sub('{' + 'orderId' + '}', escapeString(order_id))
+    
+    
+    # pull querystring keys from options
+    queryopts = options.select do |key,value|
+      query_param_keys.include? key
+    end
+
+    # header parameters, if any
+    headers = {}
+    
+    
+    # http body (model)
+    post_body = nil
+    
+    # form parameters
+    form_parameter_hash = {}
+    
+    
+    response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
+     Order.new(response)
+    
+    
+  
+  end
+
+  # Delete purchase order by ID
+  # For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+  # @param order_id ID of the order that needs to be deleted
+  # @return void
+  def self.deleteOrder (order_id, opts={})
+    query_param_keys = []
+
+    
+    
+    # set default values and merge with input
+    options = {
+      :'order_id' => order_id
+      
+    }.merge(opts)
+
+    #resource path
+    path = "/store/order/{orderId}".sub('{format}','json').sub('{' + 'orderId' + '}', escapeString(order_id))
+    
+    
+    # pull querystring keys from options
+    queryopts = options.select do |key,value|
+      query_param_keys.include? key
+    end
+
+    # header parameters, if any
+    headers = {}
+    
+    
+    # http body (model)
+    post_body = nil
+    
+    # form parameters
+    form_parameter_hash = {}
+    
+    
+    
+    Swagger::Request.new(:DELETE, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
+    
+  
+  end
+end
diff --git a/samples/client/petstore/ruby/lib/user_api.rb b/samples/client/petstore/ruby/lib/user_api.rb
index 6738cddb5f9..80a7e814421 100644
--- a/samples/client/petstore/ruby/lib/user_api.rb
+++ b/samples/client/petstore/ruby/lib/user_api.rb
@@ -8,7 +8,11 @@ class UserApi
     URI.encode(string.to_s)
   end
 
-  
+
+  # Create user
+  # This can only be done by the logged in user.
+  # @param body Created user object
+  # @return void
   def self.createUser (body, opts={})
     query_param_keys = []
 
@@ -32,7 +36,6 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -47,7 +50,6 @@ class UserApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -57,11 +59,9 @@ class UserApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -69,7 +69,10 @@ class UserApi
   
   end
 
-
+  # Creates list of users with given input array
+  # 
+  # @param body List of user object
+  # @return void
   def self.createUsersWithArrayInput (body, opts={})
     query_param_keys = []
 
@@ -93,7 +96,6 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -108,7 +110,6 @@ class UserApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -118,11 +119,9 @@ class UserApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -130,7 +129,10 @@ class UserApi
   
   end
 
-
+  # Creates list of users with given input array
+  # 
+  # @param body List of user object
+  # @return void
   def self.createUsersWithListInput (body, opts={})
     query_param_keys = []
 
@@ -154,7 +156,6 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -169,7 +170,6 @@ class UserApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -179,11 +179,9 @@ class UserApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:POST, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -191,7 +189,11 @@ class UserApi
   
   end
 
-
+  # Logs user into the system
+  # 
+  # @param username The user name for login
+  # @param password The password for login in clear text
+  # @return string
   def self.loginUser (username,password, opts={})
     query_param_keys = [:username,:password]
 
@@ -216,15 +218,12 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
      string.new(response)
@@ -233,7 +232,9 @@ class UserApi
   
   end
 
-
+  # Logs out current logged in user session
+  # 
+  # @return void
   def self.logoutUser ( opts={})
     query_param_keys = []
 
@@ -256,15 +257,12 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -272,7 +270,10 @@ class UserApi
   
   end
 
-
+  # Get user by user name
+  # 
+  # @param username The name that needs to be fetched. Use user1 for testing. 
+  # @return User
   def self.getUserByName (username, opts={})
     query_param_keys = []
 
@@ -297,15 +298,12 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     response = Swagger::Request.new(:GET, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make.body
      User.new(response)
@@ -314,7 +312,11 @@ class UserApi
   
   end
 
-
+  # Updated user
+  # This can only be done by the logged in user.
+  # @param username name that need to be deleted
+  # @param body Updated user object
+  # @return void
   def self.updateUser (username,body, opts={})
     query_param_keys = []
 
@@ -340,7 +342,6 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
@@ -355,7 +356,6 @@ class UserApi
           end
         end
         post_body = array
-
       else 
         if body.respond_to?("to_body".to_sym)
 	        post_body = body.to_body
@@ -365,11 +365,9 @@ class UserApi
       end
     end
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:PUT, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
@@ -377,7 +375,10 @@ class UserApi
   
   end
 
-
+  # Delete user
+  # This can only be done by the logged in user.
+  # @param username The name that needs to be deleted
+  # @return void
   def self.deleteUser (username, opts={})
     query_param_keys = []
 
@@ -402,20 +403,16 @@ class UserApi
     headers = {}
     
     
-
     # http body (model)
     post_body = nil
     
-
     # form parameters
     form_parameter_hash = {}
     
-
     
     
     Swagger::Request.new(:DELETE, path, {:params=>queryopts,:headers=>headers, :body=>post_body, :form_params => form_parameter_hash }).make
     
   
   end
-
 end