Clean up the api-ref for groups

The response paramaters for listing users who are members of a
group will be added in a later patch, once the users api-ref
has been cleaned up.

Change-Id: Ib08ac374f9e16aa443cc33253a84a67ab98958d0

api-ref/source/v3/groups.inc

@@ -6,22 +6,20 @@
 
 A group is a collection of users. Each group is owned by a domain.
 
-When you grant a role to a group, you explicitly associate that
+You can use groups to ease the task of managing role assignments for users.
-group with a project or domain. This action is equivalent to
+Assigning a role to a group on a project or domain is equivalent to
-granting the role to each group member on that project and domain.
+assigning the role to each group member on that project or domain.
 
-When you grant a role to a group, that role is automatically granted to any
+When you unassign a role from a group, that role is automatically unassigned
-user within the group. When you revoke a role from a group, that role is
+from any user that is a member of the group. Any tokens that authenticates those
-automatically revoked from any user within the group. Any token that
+users to the relevant project or domain are revoked.
-authenticates that user, project, and domain is revoked.
 
 As with users, a group without any role assignments is useless from the
 perspective of an OpenStack service and has no access to resources.
-However, a group without role grants is permitted as a way of
+However, a group without role assignments is permitted as a way of
 acquiring or loading users and groups from external sources before
 mapping them to projects and domains.
 
-
 Show group details
 ==================
 
@@ -37,7 +35,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - group_id: group_id
+   - group_id: group_id_path
 
 Response Parameters
 -------------------
@@ -45,11 +43,11 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - group: group
-   - name: name
+   - description: group_description_response_body
-   - links: links
+   - domain_id: group_domain_id_response_body
-   - domain_id: domain_id
+   - id: group_id_response_body
-   - id: id
+   - links: link_response_body
-   - description: description
+   - name: group_name_response_body
 
 Response Example
 ----------------
@@ -76,11 +74,11 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
+   - group_id: group_id_path
    - group: group
-   - description: description
+   - description: group_description_update_request_body
-   - name: name
+   - domain_id: group_domain_id_update_request_body
-   - domain_id: domain_id
+   - name: group_name_update_request_body
-   - group_id: group_id
 
 Request Example
 ---------------
@@ -94,11 +92,11 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - group: group
-   - name: name
+   - description: group_description_response_body
-   - links: links
+   - domain_id: group_domain_id_response_body
-   - domain_id: domain_id
+   - id: group_id_response_body
-   - id: id
+   - links: link_response_body
-   - description: description
+   - name: group_name_response_body
 
 Response Example
 ----------------
@@ -121,7 +119,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - group_id: group_id
+   - group_id: group_id_path
 
 
 Add user to group
@@ -138,8 +136,8 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
-   - group_id: group_id
+   - group_id: group_id_path
 
 
 Remove user from group
@@ -157,8 +155,8 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
-   - group_id: group_id
+   - group_id: group_id_path
 
 
 Check whether user belongs to group
@@ -176,8 +174,8 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - user_id: user_id
+   - user_id: user_id_path
-   - group_id: group_id
+   - group_id: group_id_path
 
 
 List users in group
@@ -195,20 +193,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - group_id: group_id
+   - group_id: group_id_path
-
-Response Parameters
--------------------
-
-.. rest_parameters:: parameters.yaml
-
-   - name: name
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
-   - email: email
-   - id: id
-   - users: users
 
 Response Example
 ----------------
@@ -233,9 +218,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - group: group
-   - description: description
+   - description: group_description_request_body
-   - name: name
+   - domain_id: group_domain_id_request_body
-   - domain_id: domain_id
+   - name: group_name_request_body
 
 Request Example
 ---------------
@@ -249,12 +234,17 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - group: group
-   - name: name
+   - description: group_description_response_body
-   - links: links
+   - domain_id: group_domain_id_response_body
-   - domain_id: domain_id
+   - id: group_id_response_body
-   - id: id
+   - links: link_response_body
-   - description: description
+   - name: group_name_response_body
 
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/group-show-response.json
+   :language: javascript
 
 List groups
 ===========
@@ -271,20 +261,21 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - name: name
+   - name: group_name_query
-   - domain_id: domain_id
+   - domain_id: domain_id_query
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - name: name
+   - links: link_collection
-   - links: links
-   - domain_id: domain_id
    - groups: groups
-   - id: id
+   - description: group_description_response_body
-   - description: description
+   - domain_id: group_domain_id_response_body
+   - id: group_id_response_body
+   - links: link_response_body
+   - name: group_name_response_body
 
 Response Example
 ----------------

api-ref/source/v3/parameters.yaml

@@ -136,7 +136,7 @@ user_id_path:
   type: string
 
 # variables in query
-domain_id_7:
+domain_id_query:
   description: |
     Filters the response by a domain ID.
   in: query
@@ -184,6 +184,12 @@ group_id_query:
   in: query
   required: false
   type: string
+group_name_query:
+  description: |
+    Filters the response by a group name.
+  in: query
+  required: false
+  type: string
 include_names_query:
   description: |
     If set to true, then the names of any entities returned will be include as
@@ -709,13 +715,75 @@ extras:
   type: object
 group:
   description: |
-    A ``group`` object.
+    A ``group`` object, containing:
   in: body
   required: true
   type: object
+group_description_request_body:
+  description: |
+    The description of the group.
+  in: body
+  required: true
+  type: string
+group_description_response_body:
+  description: |
+    The description of the group.
+  in: body
+  required: true
+  type: string
+group_description_update_request_body:
+  description: |
+    The new description of the group.
+  in: body
+  required: false
+  type: string
+group_domain_id_request_body:
+  description: |
+    The ID of the domain of the group.
+  in: body
+  required: true
+  type: string
+group_domain_id_response_body:
+  description: |
+    The ID of the domain of the group.
+  in: body
+  required: true
+  type: string
+group_domain_id_update_request_body:
+  description: |
+    The ID of the new domain for the group. The ability to change the domain
+    of a group is now deprecated, and will be removed in subsequent release.
+    It is already disabled by default in most Identity service implementations.
+  in: body
+  required: false
+  type: string
+group_id_response_body:
+  description: |
+    The ID of the group.
+  in: body
+  required: true
+  type: string
+group_name_request_body:
+  description: |
+    The name of the group.
+  in: body
+  required: true
+  type: string
+group_name_response_body:
+  description: |
+    The name of the group.
+  in: body
+  required: true
+  type: string
+group_name_update_request_body:
+  description: |
+    The new name of the group.
+  in: body
+  required: false
+  type: string
 groups:
   description: |
-    A ``groups`` object.
+    A list of ``group`` objects, each containing:
   in: body
   required: true
   type: array

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

@@ -1,7 +1,7 @@
 {
     "group": {
-        "domain_id": "default",
         "description": "Contract developers",
+        "domain_id": "default",
         "id": "c0d675eac29945ad9dfd08aa1bb75751",
         "links": {
             "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"

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

@@ -1,7 +1,7 @@
 {
     "group": {
-        "domain_id": "default",
         "description": "Contract developers 2016",
+        "domain_id": "default",
         "id": "c0d675eac29945ad9dfd08aa1bb75751",
         "links": {
             "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"

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

@@ -1,19 +1,29 @@
 {
-    "users": [
-        {
-            "name": "admin",
-            "links": {
-                "self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
-            },
-            "domain_id": "default",
-            "enabled": true,
-            "email": null,
-            "id": "fff603a0829d41e48bc0dd0d72ad61ce"
-        }
-    ],
     "links": {
         "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92/users",
         "previous": null,
         "next": null
+    },
+    "users": [
+        {
+            "domain_id": "default",
+            "description": null,
+            "enabled": true,
+            "id": "acd565a08293c1e48bc0dd0d72ad5d5d"
+            "name": "Henry",
+            "links": {
+                "self": "http://example.com/identity/v3/users/acd565a08293c1e48bc0dd0d72ad5d5d"
             }
+        },
+        {
+            "domain_id": "default",
+            "description": null,
+            "enabled": true,
+            "id": "fff603a0829d41e48bc0dd0d72ad61ce"
+            "name": "Paul",
+            "links": {
+                "self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
+            }
+        }
+    ]
 }

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

@@ -6,8 +6,8 @@
     },
     "groups": [
         {
-            "domain_id": "default",
             "description": "non-admin group",
+            "domain_id": "default",
             "id": "96372bbb152f475aa37e9a76a25a029c",
             "links": {
                 "self": "http://example.com/identity/v3/groups/96372bbb152f475aa37e9a76a25a029c"
@@ -15,8 +15,8 @@
             "name": "nonadmins"
         },
         {
-            "domain_id": "default",
             "description": "openstack admin group",
+            "domain_id": "default",
             "id": "9ce0ad4e58a84d7a97b92f7955d10c92",
             "links": {
                 "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92"