Move Service Provider API to its own file

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

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

Change-Id: Iabe3d443f01b173024620aae629558d228c2cd10

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

@@ -298,87 +298,7 @@ to ``ss:mem:``.
 
 .. include:: federation/mapping/mapping.inc
 
-
-.. TODO(samueldmq): This is the Service Provider API, move it to its own file.
-
-Register a Service Provider
-===========================
-
-.. rest_method::  PUT /v3/OS-FEDERATION/service_providers/{sp_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 Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-register-request.json
-   :language: javascript
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-register-response.json
-   :language: javascript
-
-
-Listing Service Providers
-=========================
-
-.. rest_method::  GET /v3/OS-FEDERATION/service_providers
-
-Normal response codes: 200
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-list-response.json
-   :language: javascript
-
-
-Get Service Provider
-====================
-
-.. rest_method::  GET /v3/OS-FEDERATION/service_providers/{sp_id}
-
-Normal response codes: 200
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-get-response.json
-   :language: javascript
-
-
-Delete Service Provider
-=======================
-
-.. rest_method::  DELETE /v3/OS-FEDERATION/service_providers/{sp_id}
-
-Normal response codes: 204
-
-
-Update Service Provider
-=======================
-
-.. rest_method::  PATCH /v3/OS-FEDERATION/service_providers/{sp_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 Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-update-request.json
-   :language: javascript
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/sp-update-response.json
-   :language: javascript
+.. include:: federation/service-provider/sp.inc
 
 
 .. TODO(samueldmq): This is the Listing Projects and Domains API, move it to its

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

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

api-ref/source/v3-ext/federation/service-provider/sp.inc

@@ -0,0 +1,80 @@
+.. -*- rst -*-
+
+Register a Service Provider
+===========================
+
+.. rest_method::  PUT /v3/OS-FEDERATION/service_providers/{sp_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 Example
+---------------
+
+.. literalinclude:: federation/service-provider/samples/register-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: federation/service-provider/samples/register-response.json
+   :language: javascript
+
+
+Listing Service Providers
+=========================
+
+.. rest_method::  GET /v3/OS-FEDERATION/service_providers
+
+Normal response codes: 200
+
+Response Example
+----------------
+
+.. literalinclude:: federation/service-provider/samples/list-response.json
+   :language: javascript
+
+
+Get Service Provider
+====================
+
+.. rest_method::  GET /v3/OS-FEDERATION/service_providers/{sp_id}
+
+Normal response codes: 200
+
+Response Example
+----------------
+
+.. literalinclude:: federation/service-provider/samples/get-response.json
+   :language: javascript
+
+
+Delete Service Provider
+=======================
+
+.. rest_method::  DELETE /v3/OS-FEDERATION/service_providers/{sp_id}
+
+Normal response codes: 204
+
+
+Update Service Provider
+=======================
+
+.. rest_method::  PATCH /v3/OS-FEDERATION/service_providers/{sp_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 Example
+---------------
+
+.. literalinclude:: federation/service-provider/samples/update-request.json
+   :language: javascript
+
+Response Example
+----------------
+
+.. literalinclude:: federation/service-provider/samples/update-response.json
+   :language: javascript