diff --git a/api-ref/source/v3-ext/federation/mapping/mapping.inc b/api-ref/source/v3-ext/federation/mapping/mapping.inc
index cdfa822d2e..998fc5cf23 100644
--- a/api-ref/source/v3-ext/federation/mapping/mapping.inc
+++ b/api-ref/source/v3-ext/federation/mapping/mapping.inc
@@ -5,20 +5,23 @@ Create a mapping
 
 .. rest_method::  PUT /v3/OS-FEDERATION/mappings/{id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
+Create a federated mapping.
 
-Normal response codes: 201
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_path
    - rules: rules
 
-Request Example
----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/create-request.json
    :language: javascript
@@ -26,14 +29,24 @@ Request Example
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_body
    - links: links
    - rules: rules
 
-Response Example
-----------------
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 201
+
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/create-response.json
    :language: javascript
@@ -44,13 +57,16 @@ Get a mapping
 
 .. rest_method::  GET /v3/OS-FEDERATION/mappings/{id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
+Get a specific federated mapping.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_path
@@ -58,14 +74,24 @@ Request
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_body
    - links: links
    - rules: rules
 
-Response Example
-----------------
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 200
+
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/get-response.json
    :language: javascript
@@ -76,20 +102,23 @@ Update a mapping
 
 .. rest_method::  PATCH /v3/OS-FEDERATION/mappings/{id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
+Update a federated mapping.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_path
    - rules: rules
 
-Request Example
----------------
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/update-request.json
    :language: javascript
@@ -97,14 +126,24 @@ Request Example
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_body
    - links: links
    - rules: rules
 
-Response Example
-----------------
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 200
+
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/update-response.json
    :language: javascript
@@ -115,20 +154,30 @@ List mappings
 
 .. rest_method::  GET /v3/OS-FEDERATION/mappings
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mappings``
+List all federated mappings.
 
-Normal response codes: 200
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mappings``
 
 Response
 --------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - links: links_collection
    - mappings: mappings
 
-Response Example
-----------------
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 200
+
+Example
+~~~~~~~
 
 .. literalinclude:: federation/mapping/samples/list-response.json
    :language: javascript
@@ -139,13 +188,23 @@ Delete a mapping
 
 .. rest_method::  DELETE /v3/OS-FEDERATION/mappings/{id}
 
-Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
+Remove a specific federated mapping.
 
-Normal response codes: 204
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping``
 
 Request
 -------
 
+Parameters
+~~~~~~~~~~
+
 .. rest_parameters:: federation/mapping/parameters.yaml
 
    - id: id_path
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success ../v3/status.yaml
+
+   - 204
\ No newline at end of file