diff --git a/api-ref/source/v3-ext/federation/mapping/mapping.inc b/api-ref/source/v3-ext/federation/mapping/mapping.inc
index fb28c4c102..c14c5f61d5 100644
--- a/api-ref/source/v3-ext/federation/mapping/mapping.inc
+++ b/api-ref/source/v3-ext/federation/mapping/mapping.inc
@@ -3,16 +3,33 @@
 Create a mapping
 ================
 
-.. rest_method::  PUT /v3/OS-FEDERATION/mappings/{mapping_id}
+.. rest_method::  PUT /v3/OS-FEDERATION/mappings/{id}
 
 Normal response codes: 201
 
+Request
+-------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_path
+   - rules: rules
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/mapping/samples/create-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_body
+   - links: links
+   - rules: rules
+
 Response Example
 ----------------
 
@@ -23,10 +40,26 @@ Response Example
 Get a mapping
 =============
 
-.. rest_method::  GET /v3/OS-FEDERATION/mappings/{mapping_id}
+.. rest_method::  GET /v3/OS-FEDERATION/mappings/{id}
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_path
+
+Response
+--------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_body
+   - links: links
+   - rules: rules
+
 Response Example
 ----------------
 
@@ -37,16 +70,33 @@ Response Example
 Update a mapping
 ================
 
-.. rest_method::  PATCH /v3/OS-FEDERATION/mappings/{mapping_id}
+.. rest_method::  PATCH /v3/OS-FEDERATION/mappings/{id}
 
 Normal response codes: 200
 
+Request
+-------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_path
+   - rules: rules
+
 Request Example
 ---------------
 
 .. literalinclude:: federation/mapping/samples/update-request.json
    :language: javascript
 
+Response
+--------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_body
+   - links: links
+   - rules: rules
+
 Response Example
 ----------------
 
@@ -61,6 +111,14 @@ List all mappings
 
 Normal response codes: 200
 
+Response
+--------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - links: links_collection
+   - mappings: mappings
+
 Response Example
 ----------------
 
@@ -71,6 +129,13 @@ Response Example
 Delete a mapping
 ================
 
-.. rest_method::  DELETE /v3/OS-FEDERATION/mappings/{mapping_id}
+.. rest_method::  DELETE /v3/OS-FEDERATION/mappings/{id}
 
 Normal response codes: 204
+
+Request
+-------
+
+.. rest_parameters:: federation/mapping/parameters.yaml
+
+   - id: id_path
diff --git a/api-ref/source/v3-ext/federation/mapping/parameters.yaml b/api-ref/source/v3-ext/federation/mapping/parameters.yaml
index f5364194f2..3eab5475f2 100644
--- a/api-ref/source/v3-ext/federation/mapping/parameters.yaml
+++ b/api-ref/source/v3-ext/federation/mapping/parameters.yaml
@@ -2,6 +2,48 @@
 
 # variables in path
 
+id_path:
+  description: |
+    The Federation Mapping unique ID
+  in: path
+  required: true
+  type: string
+
 # variables in query
 
 # variables in body
+
+id_body:
+  description: |
+    The Federation Mapping unique ID
+  in: body
+  required: true
+  type: string
+
+links:
+  description: |
+    Link to the URI where the mapping is located
+  in: body
+  required: true
+  type: object
+
+links_collection:
+  description: |
+    Link to the URI where the mapping collection is located
+  in: body
+  required: true
+  type: object
+
+mappings:
+  description: |
+    The collection of Federation Mappings
+  in: body
+  required: true
+  type: list of objects
+
+rules:
+  description: |
+    The list of rules used to map remote users into local users
+  in: body
+  required: true
+  type: object