Reorganize api-ref: v3-ext federation assertion.inc

Reorganize as per the documentation session at PTG:
https://etherpad.openstack.org/p/queens-ptg-keystone-doc-cleanup

Change-Id: I93e90e42bd1d384353c258d71a651b82f151bcc8

api-ref/source/v3-ext/federation/assertion/assertion.inc

@@ -7,8 +7,6 @@ Generate a SAML assertion
 
 .. rest_method::  POST /v3/auth/OS-FEDERATION/saml2
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2``
-
 A user may generate a SAML assertion document based on the scoped token that is
 used in the request.
 
@@ -17,15 +15,20 @@ Request Parameters:
 To generate a SAML assertion, a user must provides a scoped token ID and
 Service Provider ID in the request body.
 
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2``
+
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/assertion/parameters.yaml
 
    - auth: auth
 
-Request Example
----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/assertion/samples/saml-assertion-request.json
    :language: javascript
@@ -39,13 +42,16 @@ client is finally authenticated.
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/assertion/parameters.yaml
 
    - Headers: headers
    - xml: saml_xml
 
-Response Example
-----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/assertion/samples/saml-assertion-response.xml
    :language: xml
@@ -58,8 +64,6 @@ Generate an ECP wrapped SAML assertion
 
 .. rest_method::  POST /v3/auth/OS-FEDERATION/saml2/ecp
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2/ecp``
-
 A user may generate a SAML assertion document to work with the
 *Enhanced Client or Proxy* (ECP) profile based on the scoped token that is
 used in the request.
@@ -69,15 +73,20 @@ Request Parameters:
 To generate an ECP wrapped SAML assertion, a user must provides a scoped token
 ID and Service Provider ID in the request body.
 
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2/ecp``
+
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/assertion/parameters.yaml
 
    - auth: auth
 
-Request Example
----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/assertion/samples/ecp-saml-assertion-request.json
    :language: javascript
@@ -91,13 +100,16 @@ client is finally authenticated.
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/assertion/parameters.yaml
 
    - Headers: headers
    - xml: saml_xml
 
-Response Example
-----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/assertion/samples/ecp-saml-assertion-response.xml
    :language: xml
@@ -108,27 +120,30 @@ Retrieve Metadata properties
 
 .. rest_method::  GET /v3/OS-FEDERATION/saml2/metadata
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/metadata``
-
 A user may retrieve Metadata about an Identity Service acting as an Identity
 Provider.
 
 The response will be a full document with Metadata properties. Note that for
 readability, this example certificate has been truncated.
 
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/metadata``
+
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/assertion/parameters.yaml
 
    - Headers: headers
    - xml: metadata_xml
 
-Response Example
-----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/assertion/samples/metadata-response.xml
    :language: xml
 
 For more information about how a SAML assertion is structured, refer to the
-`specification <http://saml.xml.org/saml-specifications>`__.
+`specification <http://saml.xml.org/saml-specifications>`__.