Merge pull request #559 from wing328/java_doc

Update Java documentation for methods (endpoints)

Author: fehguy

modules/swagger-codegen/src/main/resources/Java/api.mustache

@@ -37,10 +37,12 @@ public class {{classname}} {
   }
 
   {{#operation}}
-  {{#errorList}} //error info- code: {{code}} reason: "{{reason}}" model: {{#responseModel}}{{responseModel}}
-  {{/responseModel}}{{^responseModel}}<none>
-  {{/responseModel}}
-  {{/errorList}}  
+  /**
+   * {{summary}}
+   * {{notes}}
+{{#allParams}}   * @param {{paramName}} {{description}}
+{{/allParams}}   * @return {{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}void{{/returnType}}
+   */
   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}}

samples/client/petstore/java/hello.txt

@@ -0,0 +1 @@
+Hello world!

samples/client/petstore/java/src/main/java/io/swagger/client/api/PetApi.java

@@ -36,7 +36,12 @@ public String getBasePath() {
   }
 
 
-    
+  /**
+   * 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;
 
@@ -81,7 +86,12 @@ public void updatePet (Pet body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -126,7 +136,12 @@ public void addPet (Pet body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -173,7 +188,12 @@ public List<Pet> findPetsByStatus (List<String> status) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -220,7 +240,12 @@ public List<Pet> findPetsByTags (List<String> tags) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -266,7 +291,14 @@ public Pet getPetById (Long petId) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -320,7 +352,13 @@ public void updatePetWithForm (String petId, String name, String status) throws
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -367,7 +405,14 @@ public void deletePet (String apiKey, Long petId) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 

samples/client/petstore/java/src/main/java/io/swagger/client/api/StoreApi.java

@@ -36,7 +36,11 @@ public String getBasePath() {
   }
 
 
-    
+  /**
+   * 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;
 
@@ -81,7 +85,12 @@ public Map<String, Integer> getInventory () throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -126,7 +135,12 @@ public Order placeOrder (Order body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -172,7 +186,12 @@ public Order getOrderById (String orderId) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 

samples/client/petstore/java/src/main/java/io/swagger/client/api/UserApi.java

@@ -36,7 +36,12 @@ public String getBasePath() {
   }
 
 
-    
+  /**
+   * 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;
 
@@ -81,7 +86,12 @@ public void createUser (User body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -126,7 +136,12 @@ public void createUsersWithArrayInput (List<User> body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -171,7 +186,13 @@ public void createUsersWithListInput (List<User> body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -220,7 +241,11 @@ public String loginUser (String username, String password) throws ApiException {
     }
   }
 
-    
+  /**
+   * Logs out current logged in user session
+   * 
+   * @return void
+   */
   public void logoutUser () throws ApiException {
     Object postBody = null;
 
@@ -265,7 +290,12 @@ public void logoutUser () throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -311,7 +341,13 @@ public User getUserByName (String username) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;
 
@@ -357,7 +393,12 @@ public void updateUser (String username, User body) throws ApiException {
     }
   }
 
-    
+  /**
+   * 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;