Fix the errors in params in api-ref for V3 user

This patch also take the chance to fix some examples.

Change-Id: I512d3dcc8a73d50b2bbee5f3d3b9f44c359e7416

api-ref/source/v3/parameters.yaml

@@ -163,13 +163,6 @@ effective_query:
   in: query
   required: false
   type: key-only (no value required)
-enabled_11:
-  description: |
-    Filters the response by either enabled (``true``)
-    or disabled (``false``) users.
-  in: query
-  required: false
-  type: string
 enabled_6:
   description: |
     Filters the response by either enabled (``true``)
@@ -192,6 +185,13 @@ enabled_9:
   in: query
   required: false
   type: string
+enabled_user_query:
+  description: |
+    Filters the response by either enabled (``true``)
+    or disabled (``false``) users.
+  in: query
+  required: false
+  type: string
 group_id_query:
   description: |
     Filters the response by a group ID.
@@ -241,7 +241,7 @@ name_13:
   in: query
   required: false
   type: string
-name_16:
+name_user_query:
   description: |
     Filters the response by a user name.
   in: query
@@ -396,7 +396,7 @@ credentials:
   in: body
   required: true
   type: array
-default_project_id:
+default_project_id_request_body:
   description: |
     The ID of the default project for the user.
     Setting this attribute does not grant any actual authorization on
@@ -410,11 +410,17 @@ default_project_id:
   in: body
   required: false
   type: string
-default_project_id_1:
+default_project_id_response_body:
   description: |
     The ID of the default project for the user.
   in: body
-  required: true
+  required: false
+  type: string
+default_project_id_update_body:
+  description: |
+    The new ID of the default project for the user.
+  in: body
+  required: false
   type: string
 description:
   description: |
@@ -458,12 +464,6 @@ description_4:
   in: body
   required: false
   type: string
-description_5:
-  description: |
-    The user description.
-  in: body
-  required: false
-  type: string
 description_6:
   description: |
     The project description.
@@ -592,7 +592,7 @@ domain_id_5:
   in: body
   required: true
   type: string
-domain_id_6:
+domain_id_response_body:
   description: |
     The ID of the domain for the user.
   in: body
@@ -721,18 +721,6 @@ enabled_3:
   in: body
   required: false
   type: boolean
-enabled_4:
-  description: |
-    Enables or disables the user.  An enabled user
-    can authenticate and receive authorization.  A disabled user
-    cannot authenticate or receive authorization. Additionally, all
-    tokens that the user holds become no longer valid. If you reenable
-    this user, pre-existing tokens do not become valid.  To enable the
-    user, set to ``true``. To disable the user, set to ``false``.
-    Default is ``true``.
-  in: body
-  required: false
-  type: boolean
 enabled_5:
   description: |
     Enables or disables the project and its subtree.
@@ -754,13 +742,32 @@ enabled_7:
   in: body
   required: true
   type: boolean
-enabled_8:
+enabled_user_request_body:
+  description: |
+    If the user is enabled, this value is ``true``.
+    If the user is disabled, this value is ``false``.
+  in: body
+  required: false
+  type: boolean
+enabled_user_response_body:
   description: |
     If the user is enabled, this value is ``true``.
     If the user is disabled, this value is ``false``.
   in: body
   required: true
   type: boolean
+enabled_user_update_body:
+  description: |
+    Enables or disables the user.  An enabled user
+    can authenticate and receive authorization.  A disabled user
+    cannot authenticate or receive authorization. Additionally, all
+    tokens that the user holds become no longer valid. If you reenable
+    this user, pre-existing tokens do not become valid.  To enable the
+    user, set to ``true``. To disable the user, set to ``false``.
+    Default is ``true``.
+  in: body
+  required: false
+  type: boolean
 endpoint:
   description: |
     An ``endpoint`` object.
@@ -911,12 +918,6 @@ id_13:
   in: body
   required: true
   type: string
-id_14:
-  description: |
-    The user ID.
-  in: body
-  required: true
-  type: string
 id_2:
   description: |
     A token ID.
@@ -968,6 +969,12 @@ id_9:
   in: body
   required: false
   type: string
+id_user_body:
+  description: |
+    The user ID.
+  in: body
+  required: true
+  type: string
 identity:
   description: |
     An ``identity`` object.
@@ -1093,12 +1100,6 @@ links_13:
   in: body
   required: true
   type: object
-links_14:
-  description: |
-    The links for the ``users`` resource.
-  in: body
-  required: true
-  type: object
 links_2:
   description: |
     The links for the ``endpoint`` resource.
@@ -1141,7 +1142,7 @@ links_8:
   in: body
   required: true
   type: object
-links_9:
+links_user:
   description: |
     The links for the ``user`` resource.
   in: body
@@ -1199,12 +1200,6 @@ name_11:
   in: body
   required: true
   type: string
-name_12:
-  description: |
-    The user name. Must be unique within the domain.
-  in: body
-  required: true
-  type: string
 name_15:
   description: |
     The service name.
@@ -1266,13 +1261,6 @@ name_7:
   in: body
   required: false
   type: string
-name_8:
-  description: |
-    The user name, which must be unique within the
-    owning domain.
-  in: body
-  required: true
-  type: string
 name_9:
   description: |
     The project name. The project can have the same
@@ -1321,17 +1309,11 @@ password:
   in: body
   required: true
   type: string
-password_1:
+password_request_body:
   description: |
     The password for the user.
   in: body
-  required: true
+  required: false
-  type: string
-password_2:
-  description: |
-    The new password for the user.
-  in: body
-  required: true
   type: string
 policies:
   description: |
@@ -1597,6 +1579,20 @@ user:
   in: body
   required: true
   type: object
+user_domain_id_request_body:
+  description: |
+    The ID of the domain for the user.
+  in: body
+  required: false
+  type: string
+user_domain_id_update_body:
+  description: |
+    The ID of the new domain for the user. The ability to change the domain
+    of a user is now deprecated, and will be removed in subequent release.
+    It is already disabled by default in most Identity service implementations.
+  in: body
+  required: false
+  type: string
 user_id_1:
   description: |
     The ID of the user who owns the credential.
@@ -1621,6 +1617,36 @@ user_id_5:
   in: body
   required: false
   type: string
+user_name_create_request_body:
+  description: |
+    The user name. Must be unique within the owning domain.
+  in: body
+  required: true
+  type: string
+user_name_response_body:
+  description: |
+    The user name. Must be unique within the owning domain.
+  in: body
+  required: true
+  type: string
+user_name_update_body:
+  description: |
+    The new name for the user. Must be unique within the owning domain.
+  in: body
+  required: false
+  type: string
+user_object:
+  description: |
+    A ``user`` object, containing:
+  in: body
+  required: true
+  type: object
+user_password_update_body:
+  description: |
+    The new password for the user.
+  in: body
+  required: true
+  type: string
 user_tree_dn:
   description: |
     The base distinguished name (DN) of LDAP, from
@@ -1643,4 +1669,9 @@ users:
   in: body
   required: true
   type: array
-
+users_object:
+  description: |
+    A list of ``user`` object, each containing:
+  in: body
+  required: true
+  type: array

api-ref/source/v3/samples/admin/user-create-request.json

@@ -1,9 +1,7 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "description": "James Doe user",
         "domain_id": "1789d1",
-        "email": "jdoe@example.com",
         "enabled": true,
         "name": "James Doe",
         "password": "secretsecret"

api-ref/source/v3/samples/admin/user-projects-list-response.json

@@ -5,22 +5,22 @@
             "domain_id": "161718",
             "enabled": true,
             "id": "456788",
-            "parent_id": "212223",
             "links": {
                 "self": "http://example.com/identity/v3/projects/456788"
             },
             "name": "a project name"
+            "parent_id": "212223",
         },
         {
             "description": "description of this project",
             "domain_id": "161718",
             "enabled": true,
             "id": "456789",
-            "parent_id": "212223",
             "links": {
                 "self": "http://example.com/identity/v3/projects/456789"
             },
             "name": "another domain"
+            "parent_id": "212223",
         }
     ],
     "links": {

api-ref/source/v3/samples/admin/user-show-response.json

@@ -1,9 +1,7 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "description": "John Smith's user",
         "domain_id": "1789d1",
-        "email": "jsmith@example.com",
         "enabled": true,
         "id": "9fe1d3",
         "links": {

api-ref/source/v3/samples/admin/user-update-request.json

@@ -1,8 +1,6 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "description": "James Doe's user",
-        "email": "jamesdoe@example.com",
         "enabled": true
     }
 }

api-ref/source/v3/samples/admin/user-update-response.json

@@ -1,9 +1,7 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "description": "James Doe's user",
         "domain_id": "1789d1",
-        "email": "jamesdoe@example.com",
         "enabled": true,
         "id": "ff4e51",
         "links": {

api-ref/source/v3/samples/admin/users-list-response.json

@@ -7,7 +7,6 @@
     "users": [
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "2844b2a08be147a08ef58317d6471f1f",
             "links": {
@@ -17,7 +16,6 @@
         },
         {
             "domain_id": "default",
-            "email": "test@example.com",
             "enabled": true,
             "id": "4ab84ab39de54f4d96eaff8f2145a7cd",
             "links": {
@@ -27,7 +25,6 @@
         },
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "56696a9a04864d63877a3d06a6f0b24b",
             "links": {
@@ -37,7 +34,6 @@
         },
         {
             "domain_id": "default",
-            "email": "alt_demo@example.com",
             "enabled": true,
             "id": "5acb638d15da44fc8de41b9a4bd41875",
             "links": {
@@ -47,7 +43,6 @@
         },
         {
             "domain_id": "default",
-            "email": "demo@example.com",
             "enabled": true,
             "id": "7596e862b1af473c8ed6ae99d35b51e3",
             "links": {
@@ -57,7 +52,6 @@
         },
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "802edb2141b44e77bbde241417450749",
             "links": {
@@ -67,7 +61,6 @@
         },
         {
             "domain_id": "592ab0800d3745baaf45c610fa41950a",
-            "email": "test4@example.com",
             "enabled": true,
             "id": "9aca3883784647fe9aff3a50d922489a",
             "links": {
@@ -77,7 +70,6 @@
         },
         {
             "domain_id": "default",
-            "email": "test3@example.com",
             "enabled": true,
             "id": "a1251b011f9345e68c2458b841152034",
             "links": {
@@ -87,7 +79,6 @@
         },
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "a43f46eb318041f6b712143862e3ad70",
             "links": {
@@ -97,7 +88,6 @@
         },
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "b964a9e51c0046a4a84d3f83a135a97c",
             "links": {
@@ -107,7 +97,6 @@
         },
         {
             "domain_id": "default",
-            "email": null,
             "enabled": true,
             "id": "dc87e591c0d247d5ac04e873bd8a1646",
             "links": {
@@ -117,7 +106,6 @@
         },
         {
             "domain_id": "default",
-            "email": "glance-swift@example.com",
             "enabled": true,
             "id": "ed214dc1c2c6468b926c96eca6c8aee9",
             "links": {
@@ -127,7 +115,6 @@
         },
         {
             "domain_id": "default",
-            "email": "test2@example.com",
             "enabled": true,
             "id": "f4f6587b058a4f46a00242549b430d37",
             "links": {

api-ref/source/v3/users.inc

@@ -11,7 +11,8 @@ with no assigned roles has no access to OpenStack resources.
 You can list, create, show details for, update, delete, and change
 the password for users.
 
-You can also list groups, projects, and roles for a specified user.
+You can also list groups, projects, and role assignments for a specified
+user.
 To list user roles, see `Roles <http://developer.openstack.org/api-
 ref-identity-v3.html#roles-v3>`_.
 
@@ -31,22 +32,20 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - description: description
+   - user: user_object
-   - links: links
+   - default_project_id: default_project_id_response_body
-   - user: user
+   - domain_id: domain_id_response_body
-   - enabled: enabled
+   - enabled: enabled_user_response_body
-   - email: email
+   - id: id_user_body
-   - default_project_id: default_project_id
+   - links: links_user
-   - id: id
+   - name: user_name_response_body
-   - domain_id: domain_id
-   - name: name
 
 Response Example
 ----------------
@@ -60,7 +59,8 @@ Update user
 
 .. rest_method::  PATCH /v3/users/{user_id}
 
-Updates the password for or enables or disables a user.
+Updates a user's password, or whether they are enabled or
+disabled.
 
 If the back-end driver does not support this functionality, this
 call might return the HTTP ``Not Implemented (501)`` response code.
@@ -73,15 +73,13 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - name: name
+   - user_id: user_id_path
-   - user: user
+   - user: user_object
-   - enabled: enabled
+   - default_project_id: default_project_id_update_body
-   - email: email
+   - domain_id: user_domain_id_update_body
-   - default_project_id: default_project_id
+   - enabled: enabled_user_update_body
-   - password: password
+   - name: user_name_update_body
-   - domain_id: domain_id
+   - password: user_password_update_body
-   - description: description
-   - user_id: user_id
 
 Request Example
 ---------------
@@ -94,15 +92,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - description: description
+   - user: user_object
-   - links: links
+   - default_project_id: default_project_id_response_body
-   - user: user
+   - domain_id: domain_id_response_body
-   - enabled: enabled
+   - enabled: enabled_user_response_body
-   - email: email
+   - id: id_user_body
-   - default_project_id: default_project_id
+   - links: links_user
-   - id: id
+   - name: user_name_response_body
-   - domain_id: domain_id
-   - name: name
 
 Response Example
 ----------------
@@ -125,7 +121,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
 
 
 List groups to which a user belongs
@@ -143,7 +139,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
 
 Response Example
 ----------------
@@ -166,10 +162,10 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
+   - user_id: user_id_path
+   - user: user_object
    - original_password: original_password
-   - password: password
+   - password: user_password_update_body
-   - user: user
-   - user_id: user_id
 
 Request Example
 ---------------
@@ -192,14 +188,12 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - name: name
+   - user: user_object
-   - user: user
+   - default_project_id: default_project_id_request_body
-   - enabled: enabled
+   - domain_id: user_domain_id_request_body
-   - email: email
+   - enabled: enabled_user_request_body
-   - default_project_id: default_project_id
+   - name: user_name_create_request_body
-   - password: password
+   - password: password_request_body
-   - domain_id: domain_id
-   - description: description
 
 Request Example
 ---------------
@@ -212,15 +206,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - description: description
+   - user: user_object
-   - links: links
+   - default_project_id: default_project_id_response_body
-   - user: user
+   - domain_id: domain_id_response_body
-   - enabled: enabled
+   - enabled: enabled_user_response_body
-   - email: email
+   - id: id_user_body
-   - default_project_id: default_project_id
+   - links: links_user
-   - id: id
+   - name: user_name_response_body
-   - domain_id: domain_id
-   - name: name
 
 
 List users
@@ -238,24 +230,23 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - domain_id: domain_id
+   - domain_id: domain_id_query
-   - name: name
+   - enabled: enabled_user_query
-   - enabled: enabled
+   - name: name_user_query
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - description: description
+   - links: link_collection
-   - links: links
+   - users: users_object
-   - enabled: enabled
+   - default_project_id: default_project_id_response_body
-   - email: email
+   - domain_id: domain_id_response_body
-   - default_project_id: default_project_id
+   - enabled: enabled_user_response_body
-   - id: id
+   - id: id_user_body
-   - users: users
+   - links: links_user
-   - domain_id: domain_id
+   - name: user_name_response_body
-   - name: name
 
 Response Example
 ----------------
@@ -279,7 +270,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
 
 Response Example
 ----------------