Migrate identity /v2-admin docs from api-ref repo

Docs at [1] have already been converted from WADL (SGML / XML) to RST
using fairy-slipper [2].

This commit polish the results from the conversion and migrate the v2
admin docs to our repository under 'api-ref/source' directory. Missing
parameters definitions were added. It also removes admin-extensions.inc
as it did not contain any information.

The operation of listing roles for user had it title renamed so there
is not a duplicate label warning when running the api-ref job.

The API examples were moved into '/v2-admin/samples'.

Polishing the generated RST files include:
- Removing unnecessary blank lines;
- Removing empty references.

Polishing the generated RST files do not include:
- Modifying their content;
- Modifying file names;
- Wrapping lines at the maximum of 79 chars.

Updating the documentation will be done after this migration step.

[1] https://github.com/openstack/api-site/tree/master/api-ref/source/identity/v3
[2] https://github.com/russell/fairy-slipper

Change-Id: I39d6c6197a939d77fc462c091051760d6b626d80

api-ref/source/index.inc

@@ -11,6 +11,11 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   v2-admin/admin-tenants.inc
+   v2-admin/admin-tokens.inc
+   v2-admin/admin-users.inc
+   v2-admin/admin-versions.inc
+
    v2/identity-api-extensions.inc
    v2/identity-auth.inc
    v2/versions.inc

api-ref/source/v2-admin/admin-tenants.inc

@@ -0,0 +1,106 @@
+.. -*- rst -*-
+
+=======
+Tenants
+=======
+
+
+Show tenant details, by ID
+==========================
+
+.. rest_method::  GET /v2.0/tenants/{tenantId}
+
+Shows details for a tenant, by ID.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenantId: tenantId
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/tenant-show-response.json
+   :language: javascript
+
+
+List roles for user
+===================
+
+.. rest_method::  GET /v2.0/tenants/{tenantId}/users/{userId}/roles
+
+Lists roles for a user on a tenant. Excludes global roles.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - userId: userId
+   - tenantId: tenantId
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - roles_links: roles_links
+   - roles: roles
+   - description: description
+   - name: name
+   - id: id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/roles-list-response.json
+   :language: javascript
+
+
+List tenants (admin endpoint)
+=============================
+
+.. rest_method::  GET /v2.0/tenants
+
+Lists all tenants.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Response Example
+----------------
+
+.. literalinclude:: ../v2/samples/admin/tenants-list-response.json
+   :language: javascript
+
+
+Show tenant details, by name
+============================
+
+.. rest_method::  GET /v2.0/tenants
+
+Shows details for a tenant, by name.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: name
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/tenant-show-response.json
+   :language: javascript

api-ref/source/v2-admin/admin-tokens.inc

@@ -0,0 +1,166 @@
+.. -*- rst -*-
+
+======
+Tokens
+======
+
+
+List endoints for token
+=======================
+
+.. rest_method::  GET /v2.0/tokens/{tokenId}/endpoints
+
+Lists the endpoints associated with a token.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tokenId: tokenId
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/endpoints-list-response.json
+   :language: javascript
+
+
+Authenticate for admin API
+==========================
+
+.. rest_method::  POST /v2.0/tokens
+
+Authenticates and generates a token.
+
+A REST interface provides client authentication by using the POST
+method with ``v2.0/tokens`` as the path. Include a payload of
+credentials in the body.
+
+The Identity API is a RESTful web service. It is the entry point to
+all service APIs. To access the Identity API, you must know its
+URL.
+
+Each REST request against the Identity Service requires the ``X
+-Auth-Token`` header. Clients obtain this token and the URL
+endpoints for other service APIs by supplying their valid
+credentials to the authentication service.
+
+If the authentication token has expired, this call returns the HTTP
+``unauthorized (401)`` response code.
+
+If the token has expired, this call returns the ``itemNotFound
+(404)`` response code.
+
+The Identity API treats expired tokens as no longer valid tokens.
+
+The deployment determines how long expired tokens are stored.
+
+To view the ``trust`` object, you need to set ``trust`` enable on
+the keystone configuration.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request Example
+---------------
+
+.. literalinclude:: ../v2/samples/admin/authenticate-token-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - impersonation: impersonation
+   - endpoints_links: endpoints_links
+   - serviceCatalog: serviceCatalog
+   - description: description
+   - type: type
+   - expires: expires
+   - enabled: enabled
+   - name: name
+   - access: access
+   - trustee_user_id: trustee_user_id
+   - token: token
+   - user: user
+   - issued_at: issued_at
+   - trustor_user_id: trustor_user_id
+   - endpoints: endpoints
+   - trust: trust
+   - id: id
+   - tenant: tenant
+   - metadata: metadata
+
+Response Example
+----------------
+
+.. literalinclude:: ../v2/samples/admin/authenticate-response.json
+   :language: javascript
+
+
+Validate token
+==============
+
+.. rest_method::  GET /v2.0/tokens/{tokenId}
+
+Validates a token and confirms that it belongs to a tenant.
+
+Returns the permissions relevant to a particular client. Valid
+tokens are in the ``/tokens/{tokenId}`` path. If the token is not
+valid, this call returns the ``itemNotFound (404)`` response code.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tokenId: tokenId
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/token-validate-response.json
+   :language: javascript
+
+
+Validate token (admin)
+======================
+
+.. rest_method::  HEAD /v2.0/tokens/{tokenId}
+
+Validates a token and confirms that it belongs to a tenant, for performance.
+
+Normal response codes: 200
+Error response codes:203,204,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tokenId: tokenId
+
+
+Delete token
+============
+
+.. rest_method::  DELETE /v2.0/tokens/{tokenId}
+
+Deletes a token.
+
+Error response codes:204,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tokenId: tokenId

api-ref/source/v2-admin/admin-users.inc

@@ -0,0 +1,217 @@
+.. -*- rst -*-
+
+=====
+Users
+=====
+
+
+List user global roles
+======================
+
+.. rest_method::  GET /v2.0/users/{userId}/roles
+
+Lists global roles for a user. Excludes tenant roles.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - userId: userId
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - roles_links: roles_links
+   - roles: roles
+   - description: description
+   - name: name
+   - id: id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/roles-list-response.json
+   :language: javascript
+
+
+Create user (admin endpoint)
+============================
+
+.. rest_method::  POST /v2.0/users
+
+Creates a user.
+
+Error response codes:201,413,415,405,404,403,401,400,503,409,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenantId: tenantId
+   - password: password
+   - enabled: enabled
+   - email: email
+   - name: name
+   - X-Auth-Token: X-Auth-Token
+
+Request Example
+---------------
+
+.. literalinclude:: samples/admin/user-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - username: username
+   - enabled: enabled
+   - email: email
+   - name: name
+   - id: id
+
+
+List users (admin endpoint)
+===========================
+
+.. rest_method::  GET /v2.0/users
+
+Lists all users.
+
+To show detailed information about a user by name, include the
+``name`` query parameter in the request.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - username: username
+   - users: users
+   - enabled: enabled
+   - id: id
+   - email: email
+   - name: name
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/user-show-response.json
+   :language: javascript
+
+
+Update user (admin endpoint)
+============================
+
+.. rest_method::  PUT /v2.0/users/{userId}
+
+Updates a user.
+
+Error response codes:201,413,415,405,404,403,401,400,503,409,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - username: username
+   - enabled: enabled
+   - email: email
+   - name: name
+   - userId: userId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/admin/user-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - enabled: enabled
+   - email: email
+   - name: name
+   - id: id
+
+
+Delete user (admin endpoint)
+============================
+
+.. rest_method::  DELETE /v2.0/users/{userId}
+
+Deletes a user.
+
+Error response codes:204,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - userId: userId
+
+
+Show user details (admin endpoint)
+==================================
+
+.. rest_method::  GET /v2.0/users/{userId}
+
+Shows details for a user, by ID.
+
+The `openstack user show <http://docs.openstack.org/cli-
+reference/openstack.html#openstack-user-show>`_ command supports
+showing user details by name or ID. However, the command actually
+looks up the user ID for a user name and queries the user by ID.
+
+As a workaround, complete these steps to show details for a user by
+name:
+
+- `List all users <http://developer.openstack.org/api-ref-identity-
+  admin-v2.html#admin-listUsers>`_.
+
+- In the response, find the user name for which you want to show
+  details and note its corresponding user ID.
+
+- `Show details for user <http://developer.openstack.org/api-ref-
+  identity-admin-v2.html#admin-showUser>`_.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - userId: userId
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - username: username
+   - enabled: enabled
+   - email: email
+   - name: name
+   - id: id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/admin/user-show-response.json
+   :language: javascript

api-ref/source/v2-admin/admin-versions.inc

@@ -0,0 +1,29 @@
+.. -*- rst -*-
+
+========
+Versions
+========
+
+
+Get version details
+===================
+
+.. rest_method::  GET /v2.0
+
+Gets detailed information about a version of the Identity API.
+
+Normal response codes: 200
+Error response codes:203,413,405,404,403,401,400,503,
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - location: location
+
+Response Example
+----------------
+
+.. literalinclude:: ../v2/samples/admin/version-show-response.json
+   :language: javascript

api-ref/source/v2-admin/parameters.yaml

@@ -0,0 +1,270 @@
+# variables in header
+X-Auth-Token:
+  description: |
+    A valid authentication token for an
+    administrative user.
+  in: header
+  required: true
+  type: string
+
+# variables in path
+tenantId_1:
+  description: |
+    The tenant ID.
+  in: path
+  required: false
+  type: string
+tokenId:
+  description: |
+    The authentication token for which to perform the
+    operation.
+  in: path
+  required: false
+  type: string
+userId:
+  description: |
+    The user ID.
+  in: path
+  required: false
+  type: string
+
+# variables in query
+name_2:
+  description: |
+    Filters the response by a tenant name.
+  in: query
+  required: true
+  type: string
+
+# variables in body
+access:
+  description: |
+    An ``access`` object.
+  in: body
+  required: true
+  type: string
+description:
+  description: |
+    The description of the tenant. If not set, this
+    value is ``null``.
+  in: body
+  required: true
+  type: string
+email:
+  description: |
+    The user email.
+  in: body
+  required: false
+  type: string
+email_1:
+  description: |
+    The user email.
+  in: body
+  required: true
+  type: string
+enabled:
+  description: |
+    Indicates whether the tenant is enabled or
+    disabled.
+  in: body
+  required: true
+  type: boolean
+enabled_1:
+  description: |
+    Indicates whether the user is enabled (``true``)
+    or disabled (``false``). Default is ``true``.
+  in: body
+  required: false
+  type: boolean
+enabled_2:
+  description: |
+    Indicates whether the user is enabled (``true``)
+    or disabled(``false``). The default value is ``true``.
+  in: body
+  required: true
+  type: boolean
+endpoints:
+  description: |
+    One or more ``endpoints`` objects. Each object
+    shows the ``adminURL``, ``region``, ``internalURL``, ``id``, and
+    ``publicURL`` for the endpoint.
+  in: body
+  required: true
+  type: string
+endpoints_links:
+  description: |
+    Links for the endpoint.
+  in: body
+  required: true
+  type: string
+expires:
+  description: |
+    The date and time when the token expires.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+
+    A ``null`` value indicates that the token never expires.
+  in: body
+  required: true
+  type: string
+id:
+  description: |
+    The ID of the trust.
+  in: body
+  required: false
+  type: string
+id_1:
+  description: |
+    The user ID.
+  in: body
+  required: true
+  type: string
+impersonation:
+  description: |
+    The impersonation flag.
+  in: body
+  required: false
+  type: string
+issued_at:
+  description: |
+    The date and time when the token was issued.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+  in: body
+  required: true
+  type: string
+location:
+  format: uri
+  in: body
+  required: true
+  type: string
+metadata:
+  description: |
+    A ``metadata`` object.
+  in: body
+  required: true
+  type: string
+name:
+  description: |
+    Endpoint name.
+  in: body
+  required: true
+  type: string
+name_1:
+  description: |
+    The user name.
+  in: body
+  required: true
+  type: string
+password:
+  description: |
+    The user password.
+  in: body
+  required: false
+  type: string
+roles:
+  description: |
+    The collection of roles.
+  in: body
+  required: true
+  type: array
+roles_links:
+  description: |
+    The link to the represented role collection.
+  in: body
+  required: true
+  type: array
+serviceCatalog:
+  description: |
+    A ``serviceCatalog`` object.
+  in: body
+  required: true
+  type: string
+tenant:
+  description: |
+    A ``tenant`` object.
+  in: body
+  required: true
+  type: string
+tenantId:
+  description: |
+    The tenant ID.
+  in: body
+  required: false
+  type: string
+token:
+  description: |
+    A ``token`` object.
+  in: body
+  required: true
+  type: string
+trust:
+  description: |
+    A ``trust`` object.
+  in: body
+  required: false
+  type: string
+trustee_user_id:
+  description: |
+    The trustee user ID.
+  in: body
+  required: false
+  type: string
+trustor_user_id:
+  description: |
+    The trustor user ID.
+  in: body
+  required: false
+  type: string
+type:
+  description: |
+    Endpoint type.
+  in: body
+  required: true
+  type: string
+user:
+  description: |
+    A ``user`` object, which shows the ``username``,
+    ``roles_links``, ``id``, ``roles``, and ``name``.
+  in: body
+  required: true
+  type: string
+username:
+  description: |
+    The user name of the user.
+  in: body
+  required: true
+  type: string
+username_1:
+  description: |
+    The username of user.
+  in: body
+  required: true
+  type: string
+users:
+  description: |
+    One or more ``user`` objects.
+  in: body
+  required: true
+  type: array
+

api-ref/source/v3-ext/inherit.inc

@@ -413,8 +413,8 @@ Response Example
    :language: javascript
 
 
-List roles for user
-===================
+List inherited roles for user
+=============================
 
 .. rest_method::  GET /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/inherited_to_projects