Reorganize api-ref: v3-ext trust.inc

Reorganize as per the documentation session at PTG:
https://etherpad.openstack.org/p/queens-ptg-keystone-doc-cleanup
Closes-Bug: 1747694
Change-Id: I951eaae91bf52c6a56ffd27116ac3d07e76ebf13

api-ref/source/v3-ext/parameters.yaml

@@ -93,7 +93,6 @@ user_id_path:
   type: string
 
 # variables in query
-
 since_query:
   description: |
     A timestamp used to limit the list of results to events
@@ -103,6 +102,24 @@ since_query:
   required: false
   type: string
 
+trustee_user_id_query:
+  description: |
+    Filters the response by a trustee user ID.
+    In order to list trusts for a given trustee, filter the collection using a query string
+    (e.g., ``?trustee_user_id={user_id}``).
+  in: query
+  required: false
+  type: string
+
+trustor_user_id_query:
+  description: |
+    Filters the response by a trustor user ID.
+    In order to list trusts for a given trustor, filter the collection using a query string
+    (e.g., ``?trustor_user_id={user_id}``).
+  in: query
+  required: false
+  type: string
+
 # variables in body
 allow_redelegation:
   description: |

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

@@ -63,8 +63,11 @@ If the trust has the ``impersonation`` attribute set to `true`, then the resulti
 token’s user attribute will also represent the trustor, rather than the
 authenticating user (the trustee).
 
-Request Example
+Request
-----------------
+-------
+
+Example
+~~~~~~~
 
 .. literalinclude:: samples/OS-TRUST/trust-auth-request.json
    :language: javascript
@@ -73,8 +76,11 @@ A token created from a trust will have an ``OS-TRUST:trust`` section containing
 ``id`` of the trust, the ``impersonation`` flag, the ``trustee_user_id`` and the
 ``trustor_user_id``.
 
-Response Example
+Response
-----------------
+--------
+
+Example
+~~~~~~~
 
 .. literalinclude:: samples/OS-TRUST/trust-auth-trust-response.json
    :language: javascript
@@ -83,9 +89,6 @@ A token created from a redelegated trust will have an ``OS-TRUST:trust`` section
 containing the same fields as a regular trust token, only ``redelegated_trust_id`` and
 ``redelegation_count`` are added.
 
-Response Example
-----------------
-
 .. literalinclude:: samples/OS-TRUST/trust-auth-redelegated-response.json
    :language: javascript
 
@@ -95,19 +98,16 @@ Create trust
 
 .. rest_method::  POST /v3/OS-TRUST/trusts
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts``
-
 Creates a trust.
 
-Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts``
-
-Normal response codes: 201
-
-Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust: trust
@@ -122,16 +122,19 @@ Request
    - remaining_uses: remaining_uses
    - roles: trust_roles
 
-Request Example
+Example
----------------
+~~~~~~~
 
 Status: 201 Created
 
 .. literalinclude:: samples/OS-TRUST/trust-create-request.json
    :language: javascript
 
-Response Parameters
+Response
--------------------
+--------
+
+Parameters
+~~~~~~~~~~
 
 .. rest_parameters:: parameters.yaml
 
@@ -150,8 +153,27 @@ Response Parameters
    - roles_links: roles_links
    - links: trust_links
 
-Response Example
+Status Codes
-----------------
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 201
+
+.. rest_status_code:: error ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 409
+   - 413
+   - 415
+   - 503
+
+Example
+~~~~~~~
 
 Status: 201 Created
 
@@ -163,37 +185,26 @@ List trusts
 
 .. rest_method:: GET /v3/OS-TRUST/trusts
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts``
-
 Lists all trusts.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts``
 
-Error response codes: 400, 401, 403, 404, 405, 413, 503
+Request
+-------
 
-The following optional query strings are supported:
+Parameters
+~~~~~~~~~~
 
-- ``page``
+.. rest_parameters:: parameters.yaml
-- ``per_page`` (default 30)
-- ``trustor_user_id``
-- ``trustee_user_id``
 
-In order to list trusts for a given trustor, filter the collection using a query string
+   - trustor_user_id: trustor_user_id_query
-(e.g., ``?trustor_user_id={user_id}``).
+   - trustee_user_id: trustee_user_id_query
 
-::
+Response
+--------
 
-   GET /v3/OS-TRUST/trusts?trustor_user_id=a0fdfd
+Parameters
-
+~~~~~~~~~~
-In order to list trusts for a given trustee, filter the collection using a query string
-(e.g., ``?trustee_user_id={user_id}``).
-
-::
-
-   GET /v3/OS-TRUST/trusts?trustee_user_id=86c0d5
-
-Response Parameters
--------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -212,8 +223,25 @@ Response Parameters
    - roles_links: roles_links
    - links: trust_links
 
-Response Example
+Status Codes
-----------------
+~~~~~~~~~~~~
+
+.. rest_status_code:: success  ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error  ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 413
+   - 503
+
+Example
+~~~~~~~
 
 Status: 200 OK
 
@@ -226,23 +254,25 @@ Get trust
 
 .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust``
-
 Gets the trust information for ``{trust_id}``.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust``
-
-Error response codes: 400, 401, 403, 404, 405, 413, 503
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust_id: trust_id_path
 
-Response Parameters
+Response
--------------------
+--------
+
+Parameters
+~~~~~~~~~~
 
 .. rest_parameters:: parameters.yaml
 
@@ -261,8 +291,25 @@ Response Parameters
    - roles_links: roles_links
    - links: trust_links
 
-Response Example
+Status Codes
-----------------
+~~~~~~~~~~~~
+
+.. rest_status_code:: success  ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error  ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 413
+   - 503
+
+Example
+~~~~~~~
 
 Status: 200 OK
 
@@ -275,23 +322,25 @@ Delete trust
 
 .. rest_method:: DELETE /v3/OS-TRUST/trusts/{trust_id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust``
-
 Deletes a trust with ``{trust_id}``.
 
-Normal response codes: 204
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust``
-
-Error response codes: 400, 401, 403, 404, 405, 409, 413, 415, 503
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust_id: trust_id_path
 
-Response Example
+Response
-----------------
+--------
+
+Example
+~~~~~~~
 
 Status: 204 No Content
 
@@ -301,23 +350,42 @@ List roles delegated by a trust
 
 .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles``
-
 Lists roles delegated by a trust with ``{trust_id}``.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles``
-
-Error response codes: 400, 401, 403, 404, 405, 413, 503
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust_id: trust_id_path
 
-Response Example
+Response
-----------------
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success  ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error  ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 413
+   - 503
+
+Example
+~~~~~~~
 
 Status: 200 OK
 
@@ -330,53 +398,90 @@ Check if a role is delegated by a trust
 
 .. rest_method:: HEAD /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role``
-
 Checks if a role is delegated by a trust.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role``
-
-Error response codes: 400, 401, 403, 404, 405, 413, 503
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust_id: trust_id_path
    - role_id: role_id_path
 
-Response Example
+Response
-----------------
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success  ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error  ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 413
+   - 503
+
+Example
+~~~~~~~
 
 Status: 200 OK
 
-
 Get role delegated by a trust
 =============================
 
 .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role``
-
 Gets a role with delegated by a trust.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role``
-
-Error response codes: 400, 401, 403, 404, 405, 413, 503
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: parameters.yaml
 
    - trust_id: trust_id_path
    - role_id: role_id_path
 
-Response Example
+Response
-----------------
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success  ../v3/status.yaml
+
+   - 200
+
+.. rest_status_code:: error  ../v3/status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 405
+   - 413
+   - 503
+
+Example
+~~~~~~~
 
 Status: 200 OK
 
 .. literalinclude:: samples/OS-TRUST/trust-get-role-delegated-response.json
-   :language: javascript
+   :language: javascript

releasenotes/notes/bug-1747694-48c8caa4871300e3.yaml

@@ -0,0 +1,7 @@
+---
+fixes:
+  - |
+    [`bug 1747694 <https://bugs.launchpad.net/keystone/+bug/1747694>`_]
+    The trust API reference declared support for ``page`` and ``per_page``
+    query parameters, when the actual trust API didn't support them. The
+    API reference has been updated accordingly.