api-ref: perform all 4 phases of verification for action console output

This provides the verification of the action console output.

* Return codes updated based on what's in the code
* Parameters fixed (length -1 is not actually a thing, it's suggestion
  for future enhancement; console output described; server_id should be in path).
* Add preamble for request example
* Clean up language on preamble

Part of bp:api-ref-in-rst

Change-Id: I7071a1e528b0aa8df16589facee4ed4fd62f7b4b

api-ref/source/parameters.yaml

@@ -767,6 +767,13 @@ confirmResize:
   in: body
   required: true
   type: string
+console_output:
+  in: body
+  required: true
+  type: string
+  description: |
+    The console output as a string. Control characters will be escaped
+    to create a valid json string.
 cores:
   description: |
     The number of allowed instance cores for each tenant.
@@ -1277,7 +1284,8 @@ key_pairs_1:
   type: integer
 length:
   description: |
-    The number of lines to fetch from the end of console log. ``-1`` indicates unlimited.
+    The number of lines to fetch from the end of console log. All
+    lines will be returned if this is not specified.
   in: body
   required: false
   type: string

api-ref/source/servers-action-console-output.inc

@@ -1,8 +1,4 @@
 .. -*- rst -*-
-.. needs:method_verification
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 Show Console Output (Os-Getconsoleoutput Action)
 ================================================
@@ -11,12 +7,14 @@ Show Console Output (Os-Getconsoleoutput Action)
 
 Shows console output for a server instance.
 
-Specify the ``os-getConsoleOutput`` action in the request body.
+This returns the text of the console since boot in a REST
+response. The console content may be large, you can limit it with the
+optional ``length`` parameter.
 
 Normal response codes: 200
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404)
+Error response codes: unauthorized(401), forbidden(403),
+notFound(404), conflict(409), methodNotImplemented(501)
 
 Request
 -------
@@ -24,11 +22,13 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - server_id: server_id
+  - server_id: server_id_path
   - os-getConsoleOutput: os-getConsoleOutput
   - length: length
 
-**Example Get console output: JSON request**
+**Example Get console output**
+
+This requests the last 50 lines of the server in question.
 
 .. literalinclude:: ../../doc/api_samples/os-console-output/console-output-post-req.json
    :language: javascript
@@ -36,8 +36,11 @@ Request
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+   - output: console_output
+
 **Example Get console output: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/os-console-output/console-output-post-resp.json
    :language: javascript
-