Reorganize api-ref: v3-ext federation auth

Change-Id: I1b904be87377669e5e725d093c0a329c34b8e4ea

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

@@ -5,8 +5,6 @@ Request an unscoped OS-FEDERATION token
 
 .. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol_auth``
-
 A federated ephemeral user may request an unscoped token, which can be used to
 get a scoped token.
 
@@ -27,9 +25,14 @@ federated user belongs.
 Example Identity API token response: `Various OpenStack token responses
 <identity-api-v3.md#authentication-responses>`__
 
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol_auth``
+
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/auth/parameters.yaml
 
    - idp_id: idp_id
@@ -38,13 +41,16 @@ Request
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/auth/parameters.yaml
 
    - X-Subject-Token: X-Subject-Token
    - token: unscoped_token
 
-Response Example
+Example
-----------------
+~~~~~~~
 
 .. literalinclude:: federation/auth/samples/unscoped-token-response.json
    :language: javascript
@@ -55,21 +61,24 @@ Request a scoped OS-FEDERATION token
 
 .. rest_method::  POST /v3/auth/tokens
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
-
 A federated user may request a scoped token, by using the unscoped token. A
 project or domain may be specified by either id or name. An id is sufficient to
 uniquely identify a project or domain.
 
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
+
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/auth/parameters.yaml
 
    - auth: auth
 
-Request Example
+Example
----------------
+~~~~~~~
 
 .. literalinclude:: federation/auth/samples/scoped-token-request.json
    :language: javascript
@@ -80,13 +89,16 @@ an ``OS-FEDERATION`` section added to the ``user`` portion of the token.
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/auth/parameters.yaml
 
    - X-Subject-Token: X-Subject-Token
    - token: scoped_token
 
-Response Example
+Example
-----------------
+~~~~~~~
 
 .. literalinclude:: federation/auth/samples/scoped-token-response.json
    :language: javascript
@@ -97,33 +109,40 @@ Web Single Sign On authentication (New in version 1.2)
 
 .. rest_method::  GET /v3/auth/OS-FEDERATION/websso/{protocol_id}?origin=https%3A//horizon.example.com
 
-Request
--------
-
-.. rest_parameters:: federation/auth/parameters.yaml
-
-   - protocol_id: protocol_id
-
 For Web Single Sign On (WebSSO) authentication, users are expected to enter
 another URL endpoint. Upon successful authentication, instead of issuing a
 standard unscoped token, keystone will issue JavaScript code that redirects
 the web browser to the originating Horizon. An unscoped federated token will
 be included in the form being sent.
 
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: federation/auth/parameters.yaml
+
+   - protocol_id: protocol_id
+
+
 Web Single Sign On authentication (New in version 1.3)
 ======================================================
 
 .. rest_method::  GET /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com
 
+In contrast to the above route, this route begins a Web Single Sign On request
+that is specific to the supplied Identity Provider and Protocol. Keystone will
+issue JavaScript that handles redirections in the same way as the other route.
+An unscoped federated token will be included in the form being sent.
+
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/auth/parameters.yaml
 
    - idp_id: idp_id
    - protocol_id: protocol_id
-
-In contrast to the above route, this route begins a Web Single Sign On request
-that is specific to the supplied Identity Provider and Protocol. Keystone will
-issue JavaScript that handles redirections in the same way as the other route.
-An unscoped federated token will be included in the form being sent.

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

@@ -16,14 +16,14 @@ idp_id:
     Identity Provider's unique ID
   in: path
   required: true
-  type: object
+  type: string
 
 protocol_id:
   description: |
     Federation Protocol's unique ID
   in: path
   required: true
-  type: object
+  type: string
 
 # variables in query