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

Change-Id: I66b468e40aea70e6b2cb297157f8d15aeee43880
---
 .../v3-ext/federation/assertion/assertion.inc | 38 +++++++++++++++++++
 .../federation/assertion/parameters.yaml      | 28 ++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/api-ref/source/v3-ext/federation/assertion/assertion.inc b/api-ref/source/v3-ext/federation/assertion/assertion.inc
index 000e661eac..18bf9a09f8 100644
--- a/api-ref/source/v3-ext/federation/assertion/assertion.inc
+++ b/api-ref/source/v3-ext/federation/assertion/assertion.inc
@@ -15,6 +15,13 @@ Request Parameters:
 To generate a SAML assertion, a user must provides a scoped token ID and
 Service Provider ID in the request body.
 
+Request
+-------
+
+.. rest_parameters:: federation/assertion/parameters.yaml
+
+   - auth: auth
+
 Request Example
 ---------------
 
@@ -27,6 +34,14 @@ certificate has been truncated. Server will also set two HTTP headers:
 be sent, whereas the latter remote URL where token will be issued once the
 client is finally authenticated.
 
+Response
+--------
+
+.. rest_parameters:: federation/assertion/parameters.yaml
+
+   - Headers: headers
+   - xml: saml_xml
+
 Response Example
 ----------------
 
@@ -50,6 +65,13 @@ 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.
 
+Request
+-------
+
+.. rest_parameters:: federation/assertion/parameters.yaml
+
+   - auth: auth
+
 Request Example
 ---------------
 
@@ -62,6 +84,14 @@ the certificate has been truncated. Server will also set two HTTP headers:
 be sent, whereas the latter remote URL where token will be issued once the
 client is finally authenticated.
 
+Response
+--------
+
+.. rest_parameters:: federation/assertion/parameters.yaml
+
+   - Headers: headers
+   - xml: saml_xml
+
 Response Example
 ----------------
 
@@ -80,6 +110,14 @@ Provider.
 The response will be a full document with Metadata properties. Note that for
 readability, this example certificate has been truncated.
 
+Response
+--------
+
+.. rest_parameters:: federation/assertion/parameters.yaml
+
+   - Headers: headers
+   - xml: metadata_xml
+
 Response Example
 ----------------
 
diff --git a/api-ref/source/v3-ext/federation/assertion/parameters.yaml b/api-ref/source/v3-ext/federation/assertion/parameters.yaml
index f5364194f2..a9df8559f6 100644
--- a/api-ref/source/v3-ext/federation/assertion/parameters.yaml
+++ b/api-ref/source/v3-ext/federation/assertion/parameters.yaml
@@ -5,3 +5,31 @@
 # variables in query
 
 # variables in body
+
+auth:
+  description: |
+    Auth data with user's identity and Service Provider scope information
+  in: body
+  required: true
+  type: object
+
+headers:
+  description: |
+    XML headers
+  in: body
+  required: true
+  type: object
+
+metadata_xml:
+  description: |
+    Identity Provider metadata information in XML format
+  in: body
+  required: true
+  type: object
+
+saml_xml:
+  description: |
+    SAML assertion in XML format
+  in: body
+  required: true
+  type: object