Detail Federation Auth APIs in api-ref docs

Change-Id: Ifc30c58589fd56b67c3b8f865926e78aab5c04b8

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

@@ -3,7 +3,7 @@
 Request an unscoped OS-FEDERATION token
 =======================================
 
-.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
+.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
 
 A federated ephemeral user may request an unscoped token, which can be used to
 get a scoped token.
@@ -25,6 +25,21 @@ federated user belongs.
 Example Identity API token response: `Various OpenStack token responses
 <identity-api-v3.md#authentication-responses>`__
 
+Request
+-------
+
+.. rest_parameters:: federation/auth/parameters.yaml
+
+   - idp_id: idp_id
+   - protocol_id: protocol_id
+
+Response
+--------
+
+.. rest_parameters:: federation/auth/parameters.yaml
+
+   - token: unscoped_token
+
 Response Example
 ----------------
 
@@ -41,6 +56,13 @@ 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.
 
+Request
+-------
+
+.. rest_parameters:: federation/auth/parameters.yaml
+
+   - auth: auth
+
 Request Example
 ---------------
 
@@ -50,6 +72,13 @@ Request Example
 Similarly to the returned unscoped token, the returned scoped token will have
 an ``OS-FEDERATION`` section added to the ``user`` portion of the token.
 
+Response
+--------
+
+.. rest_parameters:: federation/auth/parameters.yaml
+
+   - token: scoped_token
+
 Response Example
 ----------------
 
@@ -60,7 +89,14 @@ Response Example
 Web Single Sign On authentication (New in version 1.2)
 ======================================================
 
-.. rest_method::  GET /v3/auth/OS-FEDERATION/websso/{protocol}?origin=https%3A//horizon.example.com
+.. 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
@@ -68,12 +104,19 @@ 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.
 
-
 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
 
+Request
+-------
+
+.. 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.

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

@@ -2,6 +2,42 @@
 
 # variables in path
 
+idp_id:
+  description: |
+    Identity Provider's unique ID
+  in: path
+  required: true
+  type: object
+
+protocol_id:
+  description: |
+    Federation Protocol's unique ID
+  in: path
+  required: true
+  type: object
+
 # variables in query
 
 # variables in body
+
+auth:
+  description: |
+    Auth data containing user's identity and scope information
+  in: body
+  required: true
+  type: object
+
+scoped_token:
+  description: |
+    Federation scoped token containing methods, roles, user, scope, catalog,
+    issuance and expiry information
+  in: body
+  required: true
+  type: object
+
+unscoped_token:
+  description: |
+    Federation unscoped token containing methods and user information
+  in: body
+  required: true
+  type: object