Move Mapping API to its own file

Change I2423030bd0849c051d22f63bf60b6a5f41f72574 migrated Federation
api-ref docs into keystone repository.

Moving Mapping API to its own file is one of the TODO comments left
there, which is being addressed in this change.

Change-Id: I070f2807dc683d470ef4e5e6d758c3998009b2be

api-ref/source/v3-ext/federation.inc

@@ -296,82 +296,7 @@ to ``ss:mem:``.
 
 .. include:: federation/identity-provider/idp.inc
 
-.. TODO(samueldmq): This is the Mapping API, move it to its own file.
-
-Create a mapping
-================
-
-.. rest_method::  PUT /v3/OS-FEDERATION/mappings/{mapping_id}
-
-Normal response codes: 201
-
-Request Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-create-request.json
-   :language: javascript
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-create-response.json
-   :language: javascript
-
-
-Get a mapping
-=============
-
-.. rest_method::  GET /v3/OS-FEDERATION/mappings/{mapping_id}
-
-Normal response codes: 200
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-get-response.json
-   :language: javascript
-
-
-Update a mapping
-================
-
-.. rest_method::  PATCH /v3/OS-FEDERATION/mappings/{mapping_id}
-
-Normal response codes: 200
-
-Request Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-update-request.json
-   :language: javascript
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-update-response.json
-   :language: javascript
-
-
-List all mappings
-=================
-
-.. rest_method::  GET /v3/OS-FEDERATION/mappings
-
-Normal response codes: 200
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/mapping-list-response.json
-   :language: javascript
-
-
-Delete a mapping
-================
-
-.. rest_method::  DELETE /v3/OS-FEDERATION/mappings/{mapping_id}
-
-Normal response codes: 204
+.. include:: federation/mapping/mapping.inc
 
 
 .. TODO(samueldmq): This is the Service Provider API, move it to its own file.

api-ref/source/v3-ext/federation/mapping/mapping.inc

@@ -0,0 +1,76 @@
+.. -*- rst -*-
+
+Create a mapping
+================
+
+.. rest_method::  PUT /v3/OS-FEDERATION/mappings/{mapping_id}
+
+Normal response codes: 201
+
+Request Example
+---------------
+
+.. literalinclude:: federation/mapping/samples/create-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: federation/mapping/samples/create-response.json
+   :language: javascript
+
+
+Get a mapping
+=============
+
+.. rest_method::  GET /v3/OS-FEDERATION/mappings/{mapping_id}
+
+Normal response codes: 200
+
+Response Example
+----------------
+
+.. literalinclude:: federation/mapping/samples/get-response.json
+   :language: javascript
+
+
+Update a mapping
+================
+
+.. rest_method::  PATCH /v3/OS-FEDERATION/mappings/{mapping_id}
+
+Normal response codes: 200
+
+Request Example
+---------------
+
+.. literalinclude:: federation/mapping/samples/update-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: federation/mapping/samples/update-response.json
+   :language: javascript
+
+
+List all mappings
+=================
+
+.. rest_method::  GET /v3/OS-FEDERATION/mappings
+
+Normal response codes: 200
+
+Response Example
+----------------
+
+.. literalinclude:: federation/mapping/samples/list-response.json
+   :language: javascript
+
+
+Delete a mapping
+================
+
+.. rest_method::  DELETE /v3/OS-FEDERATION/mappings/{mapping_id}
+
+Normal response codes: 204

api-ref/source/v3-ext/federation/mapping/parameters.yaml

@@ -0,0 +1,7 @@
+# variables in header
+
+# variables in path
+
+# variables in query
+
+# variables in body