update python method documentation

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

@@ -35,14 +35,13 @@ class {{classname}}(object):
     {{newline}}
     {{#operation}}
     def {{nickname}}(self, {{#requiredParams}}{{paramName}}{{#defaultValue}} = None{{/defaultValue}}, {{/requiredParams}}**kwargs):
-        """{{summary}}
+        """{{{summary}}}
+        {{{notes}}}
 
         Args:
-            {{#allParams}}
-            {{paramName}}, {{dataType}}: {{description}} {{^optional}}(required){{/optional}}{{#optional}}(optional){{/optional}}
-            {{newline}}
+            {{#allParams}}{{paramName}}, {{dataType}}: {{{description}}} {{^optional}}(required){{/optional}}{{#optional}}(optional){{/optional}}
             {{/allParams}}
-        {{newline}}
+
         Returns: {{returnType}}
         """
 

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

@@ -32,14 +32,13 @@ class {{classname}}(object):
     {{newline}}
     {{#operation}}
     def {{nickname}}(self, {{#requiredParams}}{{paramName}}{{#defaultValue}} = None{{/defaultValue}}, {{/requiredParams}}**kwargs):
-        """{{summary}}
+        """{{{summary}}}
+        {{{notes}}}
 
         Args:
-            {{#allParams}}
-            {{paramName}}, {{dataType}}: {{description}} {{^optional}}(required){{/optional}}{{#optional}}(optional){{/optional}}
-            {{newline}}
+            {{#allParams}}{{paramName}}, {{dataType}}: {{{description}}} {{^optional}}(required){{/optional}}{{#optional}}(optional){{/optional}}
             {{/allParams}}
-        {{newline}}
+
         Returns: {{returnType}}
         """
 

samples/client/petstore/python/SwaggerPetstore-python/SwaggerPetstore/pet_api.py

@@ -35,13 +35,12 @@ class PetApi(object):
     
     def update_pet(self, **kwargs):
         """Update an existing pet
+        
 
         Args:
-            
             body, Pet: Pet object that needs to be added to the store (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -94,13 +93,12 @@ class PetApi(object):
     
     def add_pet(self, **kwargs):
         """Add a new pet to the store
+        
 
         Args:
-            
             body, Pet: Pet object that needs to be added to the store (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -153,13 +151,12 @@ class PetApi(object):
     
     def find_pets_by_status(self, **kwargs):
         """Finds Pets by status
+        Multiple status values can be provided with comma seperated strings
 
         Args:
-            
             status, list[str]: Status values that need to be considered for filter (required)
             
-            
-        
+
         Returns: list[Pet]
         """
 
@@ -218,13 +215,12 @@ class PetApi(object):
     
     def find_pets_by_tags(self, **kwargs):
         """Finds Pets by tags
+        Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
 
         Args:
-            
             tags, list[str]: Tags to filter by (required)
             
-            
-        
+
         Returns: list[Pet]
         """
 
@@ -283,13 +279,12 @@ class PetApi(object):
     
     def get_pet_by_id(self, **kwargs):
         """Find pet by ID
+        Returns a pet when ID < 10.  ID > 10 or nonintegers will simulate API error conditions
 
         Args:
-            
             pet_id, long: ID of pet that needs to be fetched (required)
             
-            
-        
+
         Returns: Pet
         """
 
@@ -351,19 +346,14 @@ class PetApi(object):
     
     def update_pet_with_form(self, **kwargs):
         """Updates a pet in the store with form data
+        
 
         Args:
-            
             pet_id, str: ID of pet that needs to be updated (required)
-            
-            
             name, str: Updated name of the pet (required)
-            
-            
             status, str: Updated status of the pet (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -425,16 +415,13 @@ class PetApi(object):
     
     def delete_pet(self, **kwargs):
         """Deletes a pet
+        
 
         Args:
-            
             api_key, str:  (required)
-            
-            
             pet_id, long: Pet id to delete (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -493,19 +480,14 @@ class PetApi(object):
     
     def upload_file(self, **kwargs):
         """uploads an image
+        
 
         Args:
-            
             pet_id, long: ID of pet to update (required)
-            
-            
             additional_metadata, str: Additional data to pass to server (required)
-            
-            
             file, file: file to upload (required)
             
-            
-        
+
         Returns: 
         """
 

samples/client/petstore/python/SwaggerPetstore-python/SwaggerPetstore/store_api.py

@@ -35,10 +35,11 @@ class StoreApi(object):
     
     def get_inventory(self, **kwargs):
         """Returns pet inventories by status
+        Returns a map of status codes to quantities
 
         Args:
             
-        
+
         Returns: map(String, int)
         """
 
@@ -94,13 +95,12 @@ class StoreApi(object):
     
     def place_order(self, **kwargs):
         """Place an order for a pet
+        
 
         Args:
-            
             body, Order: order placed for purchasing the pet (required)
             
-            
-        
+
         Returns: Order
         """
 
@@ -159,13 +159,12 @@ class StoreApi(object):
     
     def get_order_by_id(self, **kwargs):
         """Find purchase order by ID
+        For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions
 
         Args:
-            
             order_id, str: ID of pet that needs to be fetched (required)
             
-            
-        
+
         Returns: Order
         """
 
@@ -227,13 +226,12 @@ class StoreApi(object):
     
     def delete_order(self, **kwargs):
         """Delete purchase order by ID
+        For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
 
         Args:
-            
             order_id, str: ID of the order that needs to be deleted (required)
             
-            
-        
+
         Returns: 
         """
 

samples/client/petstore/python/SwaggerPetstore-python/SwaggerPetstore/user_api.py

@@ -35,13 +35,12 @@ class UserApi(object):
     
     def create_user(self, **kwargs):
         """Create user
+        This can only be done by the logged in user.
 
         Args:
-            
             body, User: Created user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -94,13 +93,12 @@ class UserApi(object):
     
     def create_users_with_array_input(self, **kwargs):
         """Creates list of users with given input array
+        
 
         Args:
-            
             body, list[User]: List of user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -153,13 +151,12 @@ class UserApi(object):
     
     def create_users_with_list_input(self, **kwargs):
         """Creates list of users with given input array
+        
 
         Args:
-            
             body, list[User]: List of user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -212,16 +209,13 @@ class UserApi(object):
     
     def login_user(self, **kwargs):
         """Logs user into the system
+        
 
         Args:
-            
             username, str: The user name for login (required)
-            
-            
             password, str: The password for login in clear text (required)
             
-            
-        
+
         Returns: str
         """
 
@@ -283,10 +277,11 @@ class UserApi(object):
     
     def logout_user(self, **kwargs):
         """Logs out current logged in user session
+        
 
         Args:
             
-        
+
         Returns: 
         """
 
@@ -336,13 +331,12 @@ class UserApi(object):
     
     def get_user_by_name(self, **kwargs):
         """Get user by user name
+        
 
         Args:
-            
             username, str: The name that needs to be fetched. Use user1 for testing.  (required)
             
-            
-        
+
         Returns: User
         """
 
@@ -404,16 +398,13 @@ class UserApi(object):
     
     def update_user(self, **kwargs):
         """Updated user
+        This can only be done by the logged in user.
 
         Args:
-            
             username, str: name that need to be deleted (required)
-            
-            
             body, User: Updated user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -472,13 +463,12 @@ class UserApi(object):
     
     def delete_user(self, **kwargs):
         """Delete user
+        This can only be done by the logged in user.
 
         Args:
-            
             username, str: The name that needs to be deleted (required)
             
-            
-        
+
         Returns: 
         """
 

samples/client/petstore/python3/client/pet_api.py

@@ -30,15 +30,14 @@ class PetApi(object):
 
     
     
-    def updatePet(self, **kwargs):
+    def update_pet(self, **kwargs):
         """Update an existing pet
+        
 
         Args:
-            
             body, Pet: Pet object that needs to be added to the store (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -47,7 +46,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method updatePet" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method update_pet" % key)
             params[key] = val
         del params['kwargs']
 
@@ -73,15 +72,14 @@ class PetApi(object):
         
         
     
-    def addPet(self, **kwargs):
+    def add_pet(self, **kwargs):
         """Add a new pet to the store
+        
 
         Args:
-            
             body, Pet: Pet object that needs to be added to the store (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -90,7 +88,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method addPet" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method add_pet" % key)
             params[key] = val
         del params['kwargs']
 
@@ -116,15 +114,14 @@ class PetApi(object):
         
         
     
-    def findPetsByStatus(self, **kwargs):
+    def find_pets_by_status(self, **kwargs):
         """Finds Pets by status
+        Multiple status values can be provided with comma seperated strings
 
         Args:
-            
             status, list[str]: Status values that need to be considered for filter (required)
             
-            
-        
+
         Returns: list[Pet]
         """
 
@@ -133,7 +130,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method findPetsByStatus" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method find_pets_by_status" % key)
             params[key] = val
         del params['kwargs']
 
@@ -168,15 +165,14 @@ class PetApi(object):
         
         
     
-    def findPetsByTags(self, **kwargs):
+    def find_pets_by_tags(self, **kwargs):
         """Finds Pets by tags
+        Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
 
         Args:
-            
             tags, list[str]: Tags to filter by (required)
             
-            
-        
+
         Returns: list[Pet]
         """
 
@@ -185,7 +181,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method findPetsByTags" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method find_pets_by_tags" % key)
             params[key] = val
         del params['kwargs']
 
@@ -220,15 +216,14 @@ class PetApi(object):
         
         
     
-    def getPetById(self, **kwargs):
+    def get_pet_by_id(self, **kwargs):
         """Find pet by ID
+        Returns a pet when ID < 10.  ID > 10 or nonintegers will simulate API error conditions
 
         Args:
-            
             pet_id, int: ID of pet that needs to be fetched (required)
             
-            
-        
+
         Returns: Pet
         """
 
@@ -237,7 +232,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method getPetById" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method get_pet_by_id" % key)
             params[key] = val
         del params['kwargs']
 
@@ -274,21 +269,16 @@ class PetApi(object):
         
         
     
-    def updatePetWithForm(self, **kwargs):
+    def update_pet_with_form(self, **kwargs):
         """Updates a pet in the store with form data
+        
 
         Args:
-            
             pet_id, str: ID of pet that needs to be updated (required)
-            
-            
             name, str: Updated name of the pet (required)
-            
-            
             status, str: Updated status of the pet (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -297,7 +287,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method updatePetWithForm" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method update_pet_with_form" % key)
             params[key] = val
         del params['kwargs']
 
@@ -328,18 +318,15 @@ class PetApi(object):
         
         
     
-    def deletePet(self, **kwargs):
+    def delete_pet(self, **kwargs):
         """Deletes a pet
+        
 
         Args:
-            
             api_key, str:  (required)
-            
-            
             pet_id, int: Pet id to delete (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -348,7 +335,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method deletePet" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method delete_pet" % key)
             params[key] = val
         del params['kwargs']
 
@@ -382,21 +369,16 @@ class PetApi(object):
         
         
     
-    def uploadFile(self, **kwargs):
+    def upload_file(self, **kwargs):
         """uploads an image
+        
 
         Args:
-            
             pet_id, int: ID of pet to update (required)
-            
-            
             additional_metadata, str: Additional data to pass to server (required)
-            
-            
             file, file: file to upload (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -405,7 +387,7 @@ class PetApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method uploadFile" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method upload_file" % key)
             params[key] = val
         del params['kwargs']
 

samples/client/petstore/python3/client/store_api.py

@@ -30,12 +30,13 @@ class StoreApi(object):
 
     
     
-    def getInventory(self, **kwargs):
+    def get_inventory(self, **kwargs):
         """Returns pet inventories by status
+        Returns a map of status codes to quantities
 
         Args:
             
-        
+
         Returns: map(String, int)
         """
 
@@ -44,7 +45,7 @@ class StoreApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method getInventory" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method get_inventory" % key)
             params[key] = val
         del params['kwargs']
 
@@ -76,15 +77,14 @@ class StoreApi(object):
         
         
     
-    def placeOrder(self, **kwargs):
+    def place_order(self, **kwargs):
         """Place an order for a pet
+        
 
         Args:
-            
             body, Order: order placed for purchasing the pet (required)
             
-            
-        
+
         Returns: Order
         """
 
@@ -93,7 +93,7 @@ class StoreApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method placeOrder" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method place_order" % key)
             params[key] = val
         del params['kwargs']
 
@@ -125,15 +125,14 @@ class StoreApi(object):
         
         
     
-    def getOrderById(self, **kwargs):
+    def get_order_by_id(self, **kwargs):
         """Find purchase order by ID
+        For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions
 
         Args:
-            
             order_id, str: ID of pet that needs to be fetched (required)
             
-            
-        
+
         Returns: Order
         """
 
@@ -142,7 +141,7 @@ class StoreApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method getOrderById" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method get_order_by_id" % key)
             params[key] = val
         del params['kwargs']
 
@@ -179,15 +178,14 @@ class StoreApi(object):
         
         
     
-    def deleteOrder(self, **kwargs):
+    def delete_order(self, **kwargs):
         """Delete purchase order by ID
+        For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
 
         Args:
-            
             order_id, str: ID of the order that needs to be deleted (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -196,7 +194,7 @@ class StoreApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method deleteOrder" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method delete_order" % key)
             params[key] = val
         del params['kwargs']
 

samples/client/petstore/python3/client/user_api.py

@@ -30,15 +30,14 @@ class UserApi(object):
 
     
     
-    def createUser(self, **kwargs):
+    def create_user(self, **kwargs):
         """Create user
+        This can only be done by the logged in user.
 
         Args:
-            
             body, User: Created user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -47,7 +46,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method createUser" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method create_user" % key)
             params[key] = val
         del params['kwargs']
 
@@ -73,15 +72,14 @@ class UserApi(object):
         
         
     
-    def createUsersWithArrayInput(self, **kwargs):
+    def create_users_with_array_input(self, **kwargs):
         """Creates list of users with given input array
+        
 
         Args:
-            
             body, list[User]: List of user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -90,7 +88,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method createUsersWithArrayInput" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method create_users_with_array_input" % key)
             params[key] = val
         del params['kwargs']
 
@@ -116,15 +114,14 @@ class UserApi(object):
         
         
     
-    def createUsersWithListInput(self, **kwargs):
+    def create_users_with_list_input(self, **kwargs):
         """Creates list of users with given input array
+        
 
         Args:
-            
             body, list[User]: List of user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -133,7 +130,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method createUsersWithListInput" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method create_users_with_list_input" % key)
             params[key] = val
         del params['kwargs']
 
@@ -159,18 +156,15 @@ class UserApi(object):
         
         
     
-    def loginUser(self, **kwargs):
+    def login_user(self, **kwargs):
         """Logs user into the system
+        
 
         Args:
-            
             username, str: The user name for login (required)
-            
-            
             password, str: The password for login in clear text (required)
             
-            
-        
+
         Returns: str
         """
 
@@ -179,7 +173,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method loginUser" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method login_user" % key)
             params[key] = val
         del params['kwargs']
 
@@ -217,12 +211,13 @@ class UserApi(object):
         
         
     
-    def logoutUser(self, **kwargs):
+    def logout_user(self, **kwargs):
         """Logs out current logged in user session
+        
 
         Args:
             
-        
+
         Returns: 
         """
 
@@ -231,7 +226,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method logoutUser" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method logout_user" % key)
             params[key] = val
         del params['kwargs']
 
@@ -257,15 +252,14 @@ class UserApi(object):
         
         
     
-    def getUserByName(self, **kwargs):
+    def get_user_by_name(self, **kwargs):
         """Get user by user name
+        
 
         Args:
-            
             username, str: The name that needs to be fetched. Use user1 for testing.  (required)
             
-            
-        
+
         Returns: User
         """
 
@@ -274,7 +268,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method getUserByName" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method get_user_by_name" % key)
             params[key] = val
         del params['kwargs']
 
@@ -311,18 +305,15 @@ class UserApi(object):
         
         
     
-    def updateUser(self, **kwargs):
+    def update_user(self, **kwargs):
         """Updated user
+        This can only be done by the logged in user.
 
         Args:
-            
             username, str: name that need to be deleted (required)
-            
-            
             body, User: Updated user object (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -331,7 +322,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method updateUser" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method update_user" % key)
             params[key] = val
         del params['kwargs']
 
@@ -362,15 +353,14 @@ class UserApi(object):
         
         
     
-    def deleteUser(self, **kwargs):
+    def delete_user(self, **kwargs):
         """Delete user
+        This can only be done by the logged in user.
 
         Args:
-            
             username, str: The name that needs to be deleted (required)
             
-            
-        
+
         Returns: 
         """
 
@@ -379,7 +369,7 @@ class UserApi(object):
         params = locals()
         for (key, val) in params['kwargs'].items():
             if key not in allParams:
-                raise TypeError("Got an unexpected keyword argument '%s' to method deleteUser" % key)
+                raise TypeError("Got an unexpected keyword argument '%s' to method delete_user" % key)
             params[key] = val
         del params['kwargs']