From 549fe62bba121642a2ed1c70a4f49c6dd0d3f898 Mon Sep 17 00:00:00 2001
From: Sean Dague <sean@dague.net>
Date: Mon, 9 May 2016 15:49:38 -0400
Subject: [PATCH] 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                | 10 +++++++-
 .../source/servers-action-console-output.inc  | 23 +++++++++++--------
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index db1ad89f7577..554e69864424 100644
--- a/api-ref/source/parameters.yaml
+++ b/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
diff --git a/api-ref/source/servers-action-console-output.inc b/api-ref/source/servers-action-console-output.inc
index d5330bc49134..5b19ec08ae0d 100644
--- a/api-ref/source/servers-action-console-output.inc
+++ b/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
-