diff --git a/api-ref/source/v3-ext/federation/service-provider/parameters.yaml b/api-ref/source/v3-ext/federation/service-provider/parameters.yaml
index f5364194f2..aa5fbddb97 100644
--- a/api-ref/source/v3-ext/federation/service-provider/parameters.yaml
+++ b/api-ref/source/v3-ext/federation/service-provider/parameters.yaml
@@ -2,6 +2,76 @@
 
 # variables in path
 
+id_path:
+  description: |
+    The Service Provider unique ID
+  in: path
+  required: true
+  type: string
+
 # variables in query
 
 # variables in body
+
+auth_url:
+  description: |
+    The URL to authenticate against
+  in: body
+  required: true
+  type: string
+
+description:
+  description: |
+    The description of the Service Provider
+  in: body
+  required: false
+  type: string
+
+enabled:
+  description: |
+    Whether the Service Provider is enabled or not
+  in: body
+  required: true
+  type: bool
+
+id_body:
+  description: |
+    The Service Provider unique ID
+  in: body
+  required: true
+  type: string
+
+links:
+  description: |
+    Link to the URI where the Service Provider is located
+  in: body
+  required: true
+  type: string
+
+links_collection:
+  description: |
+    Link to the URI where the Service Provider collection is located
+  in: body
+  required: true
+  type: string
+
+relay_state_prefix:
+  description: |
+    The prefix of the RelayState SAML attribute
+  in: body
+  required: true
+  type: string
+
+service_providers:
+  description: |
+    The list of Service Providers
+  in: body
+  required: true
+  type: list of objects
+
+sp_url:
+  description: |
+    The Service Provider's URL
+  in: body
+  required: true
+  type: string
diff --git a/api-ref/source/v3-ext/federation/service-provider/sp.inc b/api-ref/source/v3-ext/federation/service-provider/sp.inc
index cb335f211b..5c3330a3e3 100644
--- a/api-ref/source/v3-ext/federation/service-provider/sp.inc
+++ b/api-ref/source/v3-ext/federation/service-provider/sp.inc
@@ -3,18 +3,42 @@
 Register a Service Provider
 ===========================
 
-.. rest_method::  PUT /v3/OS-FEDERATION/service_providers/{sp_id}
+.. rest_method::  PUT /v3/OS-FEDERATION/service_providers/{id}
 
 Normal response codes: 201
 Error response codes: 400 Bad Request when registering a service provider with
 invalid URLs for either `auth_url` or `sp_url`.
 
+Request
+-------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - auth_url: auth_url
+   - description: description
+   - enabled: enabled
+   - id: id_path
+   - sp_url: sp_url
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/service-provider/samples/register-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - auth_url: auth_url
+   - description: description
+   - enabled: enabled
+   - id: id_body
+   - links: links
+   - relay_state_prefix: relay_state_prefix
+   - sp_url: sp_url
+
 Response Example
 ----------------
 
@@ -29,6 +53,14 @@ Listing Service Providers
 
 Normal response codes: 200
 
+Response
+--------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - links: links_collection
+   - service_providers: service_providers
+
 Response Example
 ----------------
 
@@ -39,10 +71,30 @@ Response Example
 Get Service Provider
 ====================
 
-.. rest_method::  GET /v3/OS-FEDERATION/service_providers/{sp_id}
+.. rest_method::  GET /v3/OS-FEDERATION/service_providers/{id}
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - id: id_path
+
+Response
+--------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - auth_url: auth_url
+   - description: description
+   - enabled: enabled
+   - id: id_body
+   - links: links
+   - relay_state_prefix: relay_state_prefix
+   - sp_url: sp_url
+
 Response Example
 ----------------
 
@@ -53,26 +105,57 @@ Response Example
 Delete Service Provider
 =======================
 
-.. rest_method::  DELETE /v3/OS-FEDERATION/service_providers/{sp_id}
+.. rest_method::  DELETE /v3/OS-FEDERATION/service_providers/{id}
 
 Normal response codes: 204
 
+Request
+-------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - id: id_path
+
 
 Update Service Provider
 =======================
 
-.. rest_method::  PATCH /v3/OS-FEDERATION/service_providers/{sp_id}
+.. rest_method::  PATCH /v3/OS-FEDERATION/service_providers/{id}
 
 Normal response codes: 200
 Error response codes: 400 Bad Request when updating a service provider with
 invalid URLs for either `auth_url` or `sp_url`.
 
+Request
+-------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - id: id_path
+   - auth_url: auth_url
+   - description: description
+   - enabled: enabled
+   - sp_url: sp_url
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/service-provider/samples/update-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/service-provider/parameters.yaml
+
+   - auth_url: auth_url
+   - description: description
+   - enabled: enabled
+   - id: id_body
+   - links: links
+   - relay_state_prefix: relay_state_prefix
+   - sp_url: sp_url
+
 Response Example
 ----------------