api-ref: complete verification for extensions resource

This completes all 4 phases of the extensions resource.

* List method was added
* Error codes updated as exist in code
* Updates parameters.yaml to match actual descriptions for parameters
* Update body to be a lot stronger about what our deprecation means and why.

Part of bp:api-ref-in-rst

Change-Id: I003fc1cc84cd429fbdc0c4f0847be81d920d3561

api-ref/source/extensions.inc

@@ -1,8 +1,4 @@
 .. -*- rst -*-
-.. needs:method_verification
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 =====================================
  Extensions (extensions) (DEPRECATED)
@@ -11,9 +7,59 @@
 Lists available extensions and shows information for an extension, by
 alias.
 
-OpenStack Compute API v2.0 supports extensions. However, extensions are
+Nova originally supported the concept of API extensions, that allowed
-deprecated in Compute API v2.1. For information about extensions, see
+implementations of Nova to change the API (add new resources, or
-`Extensions <http://developer.openstack.org/api-guide/compute/extensions.html>`__.
+attributes to existing resource objects) via extensions. In an attempt
+to expose to the user what was supported in a particular site, the
+extensions resource provided a list of extensions and detailed
+information on each. The net result was gratuitous differentiation in
+the API that required all users of OpenStack clouds to write specific
+code to interact with every cloud.
+
+As such, the entire extensions concept is deprecated, and will be
+removed in the near future.
+
+For information about extensions, see `Extensions
+<http://developer.openstack.org/api-guide/compute/extensions.html>`__.
+
+List Extensions
+===============
+
+.. rest_method:: GET /v2.1/{tenant_id}/extensions
+
+Lists all extensions to the API.
+
+Normal response codes: 200
+
+Error response codes: unauthorized(401)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - extensions: extensions
+  - name: extension_name
+  - alias: alias
+  - links: extension_links
+  - namespace: namespace
+  - description: extension_description
+  - updated: updated
+
+**Example List Extensions**
+
+Lists all extensions to the API.
+
+.. literalinclude:: ../../doc/api_samples/all_extensions/extensions-list-resp.json
+   :language: javascript
+
 
 Show Extension Details
 ======================
@@ -22,10 +68,9 @@ Show Extension Details
 
 Shows details for an extension, by alias.
 
-Normal response codes: 200,203
+Normal response codes: 200
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
+Error response codes: unauthorized(401), itemNotFound(404)
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404)
 
 Request
 -------
@@ -41,14 +86,16 @@ Response
 .. rest_parameters:: parameters.yaml
 
   - extension: extension
-  - name: name
+  - name: extension_name
   - alias: alias
-  - links: links
+  - links: extension_links
   - namespace: namespace
-  - description: description
+  - description: extension_description
   - updated: updated
 
-**Example Show Extension Details: JSON response**
+**Example Show Extension Details**
+
+Shows details about the ``os-agents`` extension.
 
 .. literalinclude:: ../../doc/api_samples/extension-info/extensions-get-resp.json
    :language: javascript

api-ref/source/parameters.yaml

@@ -40,12 +40,6 @@ aggregate_name:
   in: body
   required: true
   type: string
-alias_1:
-  description: |
-    An alias for the extension name. For example, ``os-server-external-events``.
-  in: path
-  required: true
-  type: string
 api_version:
   in: path
   required: true
@@ -933,12 +927,6 @@ description:
   in: body
   required: true
   type: string
-description_1:
-  description: |
-    Text describing this extension's purpose.
-  in: body
-  required: true
-  type: string
 description_2:
   description: |
     The security group description.
@@ -1005,6 +993,25 @@ extension:
   in: body
   required: true
   type: object
+extension_description:
+  description: |
+    Text describing this extension's purpose.
+  in: body
+  required: true
+  type: string
+extension_links:
+  description: |
+    Links pertaining to this extension. This is a list of dictionaries, each including
+    keys ``href`` and ``rel``.
+  in: body
+  required: true
+  type: array
+extension_name:
+  description: |
+    Name of the extension.
+  in: body
+  required: true
+  type: string
 extensions:
   description: |
     List of ``extension`` objects.
@@ -1405,13 +1412,6 @@ links:
   in: body
   required: true
   type: array
-links_1:
-  description: |
-    Links pertaining to this extension. This is a list of dictionaries, each including
-    keys ``href`` and ``rel``.
-  in: body
-  required: true
-  type: array
 lock:
   description: |
     The action.
@@ -1546,12 +1546,6 @@ server_description:
     A free form description of the server. Limited to 255 characters
     in length. Before microversion 2.19 this was set to the server
     name.
-name_8:
-  description: |
-    Name of the extension.
-  in: body
-  required: true
-  type: string
 name_9:
   description: |
     The name of floating IP pools.