diff --git a/modules/swagger-codegen/src/main/resources/Java/api.mustache b/modules/swagger-codegen/src/main/resources/Java/api.mustache
index ad26268d715..5160ed2ff40 100644
--- a/modules/swagger-codegen/src/main/resources/Java/api.mustache
+++ b/modules/swagger-codegen/src/main/resources/Java/api.mustache
@@ -36,10 +36,12 @@ public class {{classname}} {
   }
 
   {{#operation}}
-  {{#errorList}} //error info- code: {{code}} reason: "{{reason}}" model: {{#responseModel}}{{responseModel}}
-  {{/responseModel}}{{^responseModel}}<none>
-  {{/responseModel}}
-  {{/errorList}}  
+  /**
+   * {{summary}}
+   * {{notes}}{{newLine}}
+{{#allParams}}{{newLine}}   * @param {{paramName}} {{description}}
+{{/allParams}}{{newLine}}   * @return {{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}void{{/returnType}}{{newLine}}
+   */
   public {{#returnType}}{{{returnType}}} {{/returnType}}{{^returnType}}void {{/returnType}}{{nickname}} ({{#allParams}}{{{dataType}}} {{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}}) throws ApiException {
     Object postBody = {{#bodyParam}}{{paramName}}{{/bodyParam}}{{^bodyParam}}null{{/bodyParam}};
     {{#requiredParamCount}}
diff --git a/samples/client/petstore/java/src/main/java/io/swagger/client/api/PetApi.java b/samples/client/petstore/java/src/main/java/io/swagger/client/api/PetApi.java
index 21f5beea536..8e81b181483 100644
--- a/samples/client/petstore/java/src/main/java/io/swagger/client/api/PetApi.java
+++ b/samples/client/petstore/java/src/main/java/io/swagger/client/api/PetApi.java
@@ -35,7 +35,12 @@ public class PetApi {
   }
 
   
-    
+  /**
+   * Update an existing pet
+   * 
+   * @param body Pet object that needs to be added to the store
+   * @return void
+   */
   public void updatePet (Pet body) throws ApiException {
     Object postBody = body;
     
@@ -85,7 +90,12 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * Add a new pet to the store
+   * 
+   * @param body Pet object that needs to be added to the store
+   * @return void
+   */
   public void addPet (Pet body) throws ApiException {
     Object postBody = body;
     
@@ -135,7 +145,12 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * 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 List<Pet>
+   */
   public List<Pet> findPetsByStatus (List<String> status) throws ApiException {
     Object postBody = null;
     
@@ -187,7 +202,12 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * 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 List<Pet>
+   */
   public List<Pet> findPetsByTags (List<String> tags) throws ApiException {
     Object postBody = null;
     
@@ -239,7 +259,12 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * Find pet by ID
+   * Returns a pet when ID &lt; 10.  ID &gt; 10 or nonintegers will simulate API error conditions
+   * @param petId ID of pet that needs to be fetched
+   * @return Pet
+   */
   public Pet getPetById (Long petId) throws ApiException {
     Object postBody = null;
     
@@ -290,7 +315,14 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * Updates a pet in the store with form data
+   * 
+   * @param petId ID of pet that needs to be updated
+   * @param name Updated name of the pet
+   * @param status Updated status of the pet
+   * @return void
+   */
   public void updatePetWithForm (String petId, String name, String status) throws ApiException {
     Object postBody = null;
     
@@ -349,7 +381,13 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * Deletes a pet
+   * 
+   * @param apiKey 
+   * @param petId Pet id to delete
+   * @return void
+   */
   public void deletePet (String apiKey, Long petId) throws ApiException {
     Object postBody = null;
     
@@ -401,7 +439,14 @@ public class PetApi {
     }
   }
   
-    
+  /**
+   * uploads an image
+   * 
+   * @param petId ID of pet to update
+   * @param additionalMetadata Additional data to pass to server
+   * @param file file to upload
+   * @return void
+   */
   public void uploadFile (Long petId, String additionalMetadata, File file) throws ApiException {
     Object postBody = null;
     
diff --git a/samples/client/petstore/java/src/main/java/io/swagger/client/api/StoreApi.java b/samples/client/petstore/java/src/main/java/io/swagger/client/api/StoreApi.java
index 1da75191547..c0cf5243d75 100644
--- a/samples/client/petstore/java/src/main/java/io/swagger/client/api/StoreApi.java
+++ b/samples/client/petstore/java/src/main/java/io/swagger/client/api/StoreApi.java
@@ -35,7 +35,11 @@ public class StoreApi {
   }
 
   
-    
+  /**
+   * Returns pet inventories by status
+   * Returns a map of status codes to quantities
+   * @return Map<String, Integer>
+   */
   public Map<String, Integer> getInventory () throws ApiException {
     Object postBody = null;
     
@@ -85,7 +89,12 @@ public class StoreApi {
     }
   }
   
-    
+  /**
+   * Place an order for a pet
+   * 
+   * @param body order placed for purchasing the pet
+   * @return Order
+   */
   public Order placeOrder (Order body) throws ApiException {
     Object postBody = body;
     
@@ -135,7 +144,12 @@ public class StoreApi {
     }
   }
   
-    
+  /**
+   * Find purchase order by ID
+   * For valid response try integer IDs with value &lt;= 5 or &gt; 10. Other values will generated exceptions
+   * @param orderId ID of pet that needs to be fetched
+   * @return Order
+   */
   public Order getOrderById (String orderId) throws ApiException {
     Object postBody = null;
     
@@ -186,7 +200,12 @@ public class StoreApi {
     }
   }
   
-    
+  /**
+   * Delete purchase order by ID
+   * For valid response try integer IDs with value &lt; 1000. Anything above 1000 or nonintegers will generate API errors
+   * @param orderId ID of the order that needs to be deleted
+   * @return void
+   */
   public void deleteOrder (String orderId) throws ApiException {
     Object postBody = null;
     
diff --git a/samples/client/petstore/java/src/main/java/io/swagger/client/api/UserApi.java b/samples/client/petstore/java/src/main/java/io/swagger/client/api/UserApi.java
index 7b8b2cad83a..2b7cac75291 100644
--- a/samples/client/petstore/java/src/main/java/io/swagger/client/api/UserApi.java
+++ b/samples/client/petstore/java/src/main/java/io/swagger/client/api/UserApi.java
@@ -35,7 +35,12 @@ public class UserApi {
   }
 
   
-    
+  /**
+   * Create user
+   * This can only be done by the logged in user.
+   * @param body Created user object
+   * @return void
+   */
   public void createUser (User body) throws ApiException {
     Object postBody = body;
     
@@ -85,7 +90,12 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Creates list of users with given input array
+   * 
+   * @param body List of user object
+   * @return void
+   */
   public void createUsersWithArrayInput (List<User> body) throws ApiException {
     Object postBody = body;
     
@@ -135,7 +145,12 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Creates list of users with given input array
+   * 
+   * @param body List of user object
+   * @return void
+   */
   public void createUsersWithListInput (List<User> body) throws ApiException {
     Object postBody = body;
     
@@ -185,7 +200,13 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Logs user into the system
+   * 
+   * @param username The user name for login
+   * @param password The password for login in clear text
+   * @return String
+   */
   public String loginUser (String username, String password) throws ApiException {
     Object postBody = null;
     
@@ -239,7 +260,11 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Logs out current logged in user session
+   * 
+   * @return void
+   */
   public void logoutUser () throws ApiException {
     Object postBody = null;
     
@@ -289,7 +314,12 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Get user by user name
+   * 
+   * @param username The name that needs to be fetched. Use user1 for testing. 
+   * @return User
+   */
   public User getUserByName (String username) throws ApiException {
     Object postBody = null;
     
@@ -340,7 +370,13 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * 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
+   */
   public void updateUser (String username, User body) throws ApiException {
     Object postBody = body;
     
@@ -391,7 +427,12 @@ public class UserApi {
     }
   }
   
-    
+  /**
+   * Delete user
+   * This can only be done by the logged in user.
+   * @param username The name that needs to be deleted
+   * @return void
+   */
   public void deleteUser (String username) throws ApiException {
     Object postBody = null;