Document get auth/catalog,projects,domains

This patch adds GET /auth/catalog, GET /auth/projects and GET /auth/domains
to the API site.

Change-Id: Ifda4676680bb9759348bbf7f3353741c45308b8c
Closes-bug: #1609178

api-ref/source/v3/authenticate-v3.inc

@@ -438,3 +438,127 @@ Request
 
    - X-Auth-Token: X-Auth-Token
    - X-Subject-Token: X-Subject-Token
+
+
+Get service catalog
+===================
+
+.. rest_method:: GET /v3/auth/catalog
+
+New in version 3.3
+
+This call returns a service catalog for the X-Auth-Token provided in the
+request, even if the token does not contain a catalog itself (for example,
+if it was generated using ?nocatalog).
+
+The structure of the catalog object is identical to that contained in a token.
+
+Normal response codes: 204
+Error response codes: 413,415,405,404,403,401,400,503,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Auth-Token: X-Auth-Token
+   - X-Subject-Token: X-Subject-Token
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoints: endpoints
+   - id: service_id
+   - type: type
+   - name: name_15
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/get-service-catalog-response.json
+   :language: javascript
+
+
+Get available project scopes
+============================
+
+.. rest_method:: GET /v3/auth/projects
+
+New in version 3.3
+
+This call returns the list of projects that are available to be scoped
+to based on the X-Auth-Token provided in the request.
+
+The structure of the response is exactly the same as listing projects
+for a user.
+
+Normal response codes: 204
+Error response codes: 413,415,405,404,403,401,400,503,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Auth-Token: X-Auth-Token
+   - X-Subject-Token: X-Subject-Token
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id
+   - links: links_project
+   - name: project_name_response_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/get-available-project-scopes-response.json
+   :language: javascript
+
+
+Get available domain scopes
+===========================
+
+.. rest_method:: GET /v3/auth/domains
+
+New in version 3.3
+
+This call returns the list of domains that are available to be scoped
+to based on the X-Auth-Token provided in the request.
+
+The structure is the same as listing domains.
+
+Normal response codes: 204
+Error response codes: 413,415,405,404,403,401,400,503,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Auth-Token: X-Auth-Token
+   - X-Subject-Token: X-Subject-Token
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - description: domain_description_response_body
+   - enabled: domain_enabled_response_body
+   - id: domain_id_response_body
+   - links: domain_link_response_body
+   - name: domain_name_response_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/get-available-domain-scopes-response.json
+   :language: javascript

api-ref/source/v3/parameters.yaml

@@ -1231,6 +1231,12 @@ links_7:
   in: body
   required: true
   type: object
+links_project:
+  description: |
+    The links for the ``project`` resource.
+  in: body
+  required: true
+  type: object
 links_region:
   description: |
     The links for the ``region`` resource.

api-ref/source/v3/samples/admin/get-available-domain-scopes-response.json

@@ -0,0 +1,27 @@
+{
+    "domains": [
+        {
+            "description": "my domain description",
+            "enabled": true,
+            "id": "1789d1",
+            "links": {
+                "self": "https://example.com/identity/v3/domains/1789d1"
+            },
+            "name": "my domain"
+        },
+        {
+            "description": "description of my other domain",
+            "enabled": true,
+            "id": "43e8da",
+            "links": {
+                "self": "https://example.com/identity/v3/domains/43e8da"
+            },
+            "name": "another domain"
+        }
+    ],
+    "links": {
+        "self": "https://example.com/identity/v3/auth/domains",
+        "previous": null,
+        "next": null
+    }
+}

api-ref/source/v3/samples/admin/get-available-project-scopes-response.json

@@ -0,0 +1,27 @@
+{
+    "projects": [
+        {
+            "domain_id": "1789d1",
+            "enabled": true,
+            "id": "263fd9",
+            "links": {
+                "self": "https://example.com/identity/v3/projects/263fd9"
+            },
+            "name": "Test Group"
+        },
+        {
+            "domain_id": "1789d1",
+            "enabled": true,
+            "id": "50ef01",
+            "links": {
+                "self": "https://example.com/identity/v3/projects/50ef01"
+            },
+            "name": "Build Group"
+        }
+    ],
+    "links": {
+        "self": "https://example.com/identity/v3/auth/projects",
+        "previous": null,
+        "next": null
+    }
+}

api-ref/source/v3/samples/admin/get-service-catalog-response.json

@@ -0,0 +1,34 @@
+{
+    "catalog": [
+        {
+            "endpoints": [
+                {
+                    "id": "39dc322ce86c4111b4f06c2eeae0841b",
+                    "interface": "public",
+                    "region": "RegionOne",
+                    "url": "http://localhost:5000"
+                },
+                {
+                    "id": "ec642f27474842e78bf059f6c48f4e99",
+                    "interface": "internal",
+                    "region": "RegionOne",
+                    "url": "http://localhost:5000"
+                },
+                {
+                    "id": "c609fc430175452290b62a4242e8a7e8",
+                    "interface": "admin",
+                    "region": "RegionOne",
+                    "url": "http://localhost:35357"
+                }
+            ],
+            "id": "4363ae44bdf34a3981fde3b823cb9aa2",
+            "type": "identity",
+            "name": "keystone"
+        }
+    ],
+    "links": {
+        "self": "https://example.com/identity/v3/catalog",
+        "previous": null,
+        "next": null
+    }
+}