user creation api extension: Added temp password feature from admin ui into users api call

Created by: duk3luk3

This pull request

• fixes outdated comments in the POST /users api call
• adds the parameter expired_password to the call which if set will cause the password to be set expired
• adds the parameter force_random_password to the call which if set will cause the password to be randomly generated

To properly handle the more complex logic needed to make this change backwards-compatible and robust, some code had to be added. Comments were inserted where expedient.

I believe it is self-evident that adding the "generate temp password" feature that is already in the admin ui to the api call is useful. It enables for example batch-adding users with random passwords.

lib/api/users.rb

@@ -30,19 +30,19 @@ module API
       # Create user. Available only for admin
       #
       # Parameters:
-      #   email (required)                                          - Email
-      #   password (required unless force_random_password is set)   - Password
-      #   name (required)                                           - Name
-      #   username (required)                                       - username
-      #   skype                                                     - Skype ID
-      #   linkedin                                                  - Linkedin
-      #   twitter                                                   - Twitter account
-      #   projects_limit                                            - Number of projects user can create
-      #   extern_uid                                                - External authentication provider UID
-      #   provider                                                  - External provider
-      #   bio                                                       - Bio
-      #   expired_password                                          - password is set expired
-      #   force_random_password (required unless password is set)   - generate random password for user
+      #   email (required)                                                    - Email
+      #   password (required unless force_random_password is set)             - Password
+      #   name (required)                                                     - Name
+      #   username (required)                                                 - username
+      #   skype                                                               - Skype ID
+      #   linkedin                                                            - Linkedin
+      #   twitter                                                             - Twitter account
+      #   projects_limit                                                      - Number of projects user can create
+      #   extern_uid                                                          - External authentication provider UID
+      #   provider                                                            - External provider
+      #   bio                                                                 - Bio
+      #   expired_password (true/false)                                       - password is set expired
+      #   force_random_password (true/false; required unless password is set) - generate random password for user
       # Example Request:
       #   POST /users
       post do