Detail IdP APIs in api-ref docs

Change-Id: Ic478a53c92d5f9fa70adb7a3aae014c1ff1df0df

api-ref/source/v3-ext/federation/identity-provider/idp.inc

@@ -3,17 +3,38 @@
 Register an Identity Provider
 =============================
 
-.. rest_method::  PUT /v3/OS-FEDERATION/identity_providers/{idp_id}
+.. rest_method::  PUT /v3/OS-FEDERATION/identity_providers/{id}
 
 Normal response codes: 201
 Error response codes: 409
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - description: description
+    - enabled: enabled
+    - id: id_path
+    - remote_ids: remote_ids
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/identity-provider/samples/register-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - description: description
+    - enabled: enabled
+    - id: id_body
+    - links: links
+    - remote_ids: remote_ids
+
 Response Example
 ----------------
 
@@ -28,6 +49,21 @@ List identity providers
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - id: id_query
+    - enabled: enabled_query
+
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - identity_providers: identity_providers
+
 Response Example
 ----------------
 
@@ -38,10 +74,28 @@ Response Example
 Get Identity provider
 =====================
 
-.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{idp_id}
+.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{id}
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - id: id_path
+
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - description: description
+    - enabled: enabled
+    - id: id_body
+    - links: links
+    - remote_ids: remote_ids
+
 Response Example
 ----------------
 
@@ -52,18 +106,24 @@ Response Example
 Delete identity provider
 ========================
 
-.. rest_method::  DELETE /v3/OS-FEDERATION/identity_providers/{idp_id}
+.. rest_method::  DELETE /v3/OS-FEDERATION/identity_providers/{id}
 
 When an identity provider is deleted, any tokens generated by that identity
 provider will be revoked.
 
 Normal response codes: 204
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - id: id_path
 
 Update identity provider
 ========================
 
-.. rest_method::  PATCH /v3/OS-FEDERATION/identity_providers/{idp_id}
+.. rest_method::  PATCH /v3/OS-FEDERATION/identity_providers/{id}
 
 When an identity provider is disabled, any tokens generated by that identity
 provider will be revoked.
@@ -71,12 +131,32 @@ provider will be revoked.
 Normal response codes: 200
 Error response codes: 409
 
+Request
+-------
+
+Any attribute of an Identity Provider may be passed in the request body.
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - id: id_path
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/identity-provider/samples/update-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - description: description
+    - enabled: enabled
+    - id: id_body
+    - links: links
+    - remote_ids: remote_ids
+
 Response Example
 ----------------
 
@@ -91,12 +171,28 @@ Add a protocol and attribute mapping to an identity provider
 
 Normal response codes: 201
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - idp_id: id_path
+    - protocol_id: protocol_id
+    - protocol: protocol
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/identity-provider/samples/add-protocol-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - protocol: protocol
+
 Response Example
 ----------------
 
@@ -107,10 +203,26 @@ Response Example
 List all protocol and attribute mappings of an identity provider
 ================================================================
 
-.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols
+.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{id}/protocols
 
 Normal response codes: 200
 
+
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - id: id_path
+
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - protocols: protocols
+    - links: protocols_links
+
 Response Example
 ----------------
 
@@ -125,6 +237,21 @@ Get a protocol and attribute mapping for an identity provider
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - idp_id: id_path
+    - protocol_id: protocol_id
+
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - protocol: protocol
+
 Response Example
 ----------------
 
@@ -139,12 +266,28 @@ Update the attribute mapping for an identity provider and protocol
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - idp_id: id_path
+    - protocol_id: protocol_id
+    - protocol: protocol
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/identity-provider/samples/update-protocol-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - protocol: protocol
+
 Response Example
 ----------------
 
@@ -157,4 +300,12 @@ Delete a protocol and attribute mapping from an identity provider
 
 .. rest_method::  DELETE /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
 
-Normal response codes: 204
+Normal response codes: 204
+
+Request
+-------
+
+.. rest_parameters:: federation/identity-provider/parameters.yaml
+
+    - idp_id: id_path
+    - protocol_id: protocol_id

api-ref/source/v3-ext/federation/identity-provider/parameters.yaml

@@ -2,6 +2,96 @@
 
 # variables in path
 
+id_path:
+  description: |
+    The Identity Provider ID
+  in: path
+  required: true
+  type: string
+
+protocol_id:
+  description: |
+    The federation protocol ID
+  in: path
+  required: true
+  type: string
+
 # variables in query
 
+enabled_query:
+  description: |
+    Filter for Identity Providers' enabled attribute
+  in: query
+  required: false
+  type: bool
+
+id_query:
+  description: |
+    Filter for Identity Providers' ID attribute
+  in: query
+  type: string
+
 # variables in body
+
+description:
+  description: |
+    The Identity Provider description
+  in: body
+  required: false
+  type: string
+
+enabled:
+  description: |
+    Whether the Identity Provider is enabled or not
+  in: body
+  required: true
+  type: bool
+
+id_body:
+  description: |
+    The Identity Provider unique ID
+  in: body
+  required: true
+  type: string
+
+identity_providers:
+  description: |
+    List of Identity Providers
+  in: body
+  required: true
+  type: array of objects
+
+links:
+  description: |
+    Links containing URI to the Identity Provider resource and its Protocols
+  in: body
+  required: true
+  type: object
+
+protocol:
+  description: |
+    The Federation Protocol object
+  in: body
+  required: true
+  type: object
+
+protocols:
+  description: |
+    List of Federation Protocols
+  in: body
+  required: true
+  type: list of objects
+
+protocols_links:
+  description: |
+    Link containing the URI to the collection of Federation Protocols
+  in: body
+  required: true
+  type: object
+
+remote_ids:
+  description: |
+    List of the unique Identity Provider's remote IDs
+  in: body
+  required: true
+  type: array of strings