From ae52a62c0963e2485e74786f38e4d29c51060d0c Mon Sep 17 00:00:00 2001 From: William Cheng Date: Thu, 26 Mar 2015 16:27:00 +0800 Subject: [PATCH] update java doc --- .../src/main/resources/Java/api.mustache | 10 +-- .../java/io/swagger/client/api/PetApi.java | 61 ++++++++++++++++--- .../java/io/swagger/client/api/StoreApi.java | 27 ++++++-- .../java/io/swagger/client/api/UserApi.java | 57 ++++++++++++++--- 4 files changed, 131 insertions(+), 24 deletions(-) diff --git a/modules/swagger-codegen/src/main/resources/Java/api.mustache b/modules/swagger-codegen/src/main/resources/Java/api.mustache index 20829f8297b..b6c87b4da14 100644 --- a/modules/swagger-codegen/src/main/resources/Java/api.mustache +++ b/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}} - {{/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 cf6cdc3f0c9..234cdadece2 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 @@ -36,7 +36,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; @@ -81,7 +86,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; @@ -126,7 +136,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 + */ public List findPetsByStatus (List status) throws ApiException { Object postBody = null; @@ -173,7 +188,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 + */ public List findPetsByTags (List tags) throws ApiException { Object postBody = null; @@ -220,7 +240,12 @@ public class PetApi { } } - + /** + * Find pet by ID + * Returns a pet when ID < 10. ID > 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 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; @@ -320,7 +352,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; @@ -367,7 +405,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 318c55df21e..cff340e69d7 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 @@ -36,7 +36,11 @@ public class StoreApi { } - + /** + * Returns pet inventories by status + * Returns a map of status codes to quantities + * @return Map + */ public Map getInventory () throws ApiException { Object postBody = null; @@ -81,7 +85,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; @@ -126,7 +135,12 @@ public class StoreApi { } } - + /** + * Find purchase order by ID + * For valid response try integer IDs with value <= 5 or > 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 class StoreApi { } } - + /** + * Delete purchase order by ID + * For valid response try integer IDs with value < 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 e50c034ab16..2296c0223ce 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 @@ -36,7 +36,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; @@ -81,7 +86,12 @@ public class UserApi { } } - + /** + * Creates list of users with given input array + * + * @param body List of user object + * @return void + */ public void createUsersWithArrayInput (List body) throws ApiException { Object postBody = body; @@ -126,7 +136,12 @@ public class UserApi { } } - + /** + * Creates list of users with given input array + * + * @param body List of user object + * @return void + */ public void createUsersWithListInput (List body) throws ApiException { Object postBody = body; @@ -171,7 +186,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; @@ -220,7 +241,11 @@ public class UserApi { } } - + /** + * Logs out current logged in user session + * + * @return void + */ public void logoutUser () throws ApiException { Object postBody = null; @@ -265,7 +290,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; @@ -311,7 +341,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; @@ -357,7 +393,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;