From b62acaa3c011a20e544650f0614bb9e2a357cc7d Mon Sep 17 00:00:00 2001
From: Samuel de Medeiros Queiroz <samueldmq@gmail.com>
Date: Fri, 12 Aug 2016 17:03:09 -0300
Subject: [PATCH] Detail Federation Auth APIs in api-ref docs

Change-Id: Ifc30c58589fd56b67c3b8f865926e78aab5c04b8
---
 .../source/v3-ext/federation/auth/auth.inc    | 49 +++++++++++++++++--
 .../v3-ext/federation/auth/parameters.yaml    | 36 ++++++++++++++
 2 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/api-ref/source/v3-ext/federation/auth/auth.inc b/api-ref/source/v3-ext/federation/auth/auth.inc
index 4b261efdca..bb9c215e49 100644
--- a/api-ref/source/v3-ext/federation/auth/auth.inc
+++ b/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.
diff --git a/api-ref/source/v3-ext/federation/auth/parameters.yaml b/api-ref/source/v3-ext/federation/auth/parameters.yaml
index f5364194f2..f187af0765 100644
--- a/api-ref/source/v3-ext/federation/auth/parameters.yaml
+++ b/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