api-ref: document floating ip pools endpoint

Neutron patch: https://review.openstack.org/#/c/555088/

Depends-On: Iaa995630645042520df67d95271e14f11ffcff8c
Change-Id: I88110de8d9d4151b8e8e14172b5dcd4e804eee1e
Related-Bug: #1653932

api-ref/source/v2/floatingippools.inc

@@ -0,0 +1,38 @@
+====================================
+Floating IP pools (floatingip_pools)
+====================================
+
+Lists floating IP pools.
+
+List floating IP Pools
+======================
+
+.. rest_method::  GET /v2.0/floatingip_pools
+
+Lists floating IP pools visible to the user.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - floatingip_pools: floatingip_pools
+   - subnet_id: subnet-id-body
+   - network_id: subnet-network_id
+   - subnet_name: subnet-name
+   - tenant_id: project_id
+   - project_id: project_id
+   - cidr: cidr
+
+Response Example
+----------------
+
+.. literalinclude:: samples/floatingips/floating-ip-pools-list-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -26,6 +26,7 @@ Layer 3 Networking
 ##################
 .. include:: address-scopes.inc
 .. include:: floatingips.inc
+.. include:: floatingippools.inc
 .. include:: fip-port-forwarding.inc
 .. include:: routers.inc
 .. include:: subnetpools.inc

api-ref/source/v2/parameters.yaml

@@ -3159,6 +3159,12 @@ floatingip-subnet_id:
   in: body
   required: false
   type: string
+floatingip_pools:
+  description: |
+    A list of ``floatingip_pools`` objects.
+  in: body
+  required: true
+  type: array
 floatingips:
   description: |
     A list of ``floatingip`` objects.

api-ref/source/v2/samples/floatingips/floating-ip-pools-list-response.json

@@ -0,0 +1,12 @@
+{
+    "floatingip_pools": [
+        {
+            "subnet_id": "cdec285c-b157-48aa-900c-e77f6bd958e5",
+            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
+            "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+            "subnet_name": "public-subnet",
+            "cidr": "192.0.0.0/8",
+            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e"
+        }
+    ]
+}