Add api-ref for container execute

This patch adds api-ref for container execute.

Change-Id: I3b37e13e7e2990d61caabf6d5b455468529b70d8
Closes-Bug: #1720925

api-ref/source/containers.inc

@@ -7,8 +7,8 @@
 Lists, creates, shows details for, stats, updates, deletes, starts, resizes,
 stops, pauses, unpauses, restarts, renames, commits, kills, attaches to containers,
 gets archive from container, puts archive to container, and adds security group
-for specified container, gets logs of a container, displays the running
-processes in a container.
+for specified container, executes command in a running container, gets logs
+of a container, displays the running processes in a container.
 
 Create new container
 ====================
@@ -991,6 +991,63 @@ This request does not return anything in the response body.
   - X-Openstack-Request-Id: request_id
 
 
+Execute command in a running container
+======================================
+
+.. rest_method:: POST /v1/containers/{container_ident}/execute?command={command}&run={run}&interactive={interactive}
+
+Execute command in a running container.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - container_ident: container_ident
+   - command: exec_command
+   - run: exec_run
+   - interactive: exec_interactive
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - exec_output: exec_output
+  - exec_exit_code: exec_exit_code
+  - exec_id: exec_id
+  - exec_url: exec_url
+
+.. note::
+
+   There are two possible responses. If the run parameter is set to true,
+   the output will be {"output": "...", "exit_code": "..."}. Otherwise,
+   the output will be {"exec_id": "...", "url": "..."}.
+
+Response Example
+----------------
+
+.. literalinclude:: samples/container-execute-resp.json
+   :language: javascript
+
+.. literalinclude:: samples/container-execute-resp-2.json
+   :language: javascript
+
+
 Get logs of a container
 =======================
 

api-ref/source/parameters.yaml

@@ -23,6 +23,27 @@ destination_path:
   in: query
   required: true
   type: string
+exec_command:
+  description: |
+    The command to execute in a container.
+  in: query
+  required: true
+  type: string
+exec_interactive:
+  description: |
+    Keep STDIN open even if not attached, allocate a pseudo-TTY.
+  in: query
+  required: false
+  type: boolean
+exec_run:
+  description: |
+    Whether to run the command or not. If this parameter is set to true,
+    Zun will run the command right away. If this parameter is set to false,
+    Zun won't run the command but return the necessary information (i.e. the
+    URL and execution id) for users to trigger the execution of the command.
+  in: query
+  required: false
+  type: boolean
 force:
   description: |
     Specify to delete container forcefully.
@@ -59,6 +80,12 @@ repository:
   in: query
   required: true
   type: string
+run:
+  description: |
+    Set false if enabled interactive.
+  in: query
+  required: false
+  type: boolean
 security_group_query:
   description: |
     Security groups to be added to the container.
@@ -207,6 +234,26 @@ environment:
     The environment variables.
   in: body
   type: array
+exec_exit_code:
+  description: |
+    The exit code of the command executed in a container.
+  in: body
+  type: dict
+exec_id:
+  description: |
+    The ID of the exec instance.
+  in: body
+  type: dict
+exec_output:
+  description: |
+    The output of the command executed in a container.
+  in: body
+  type: dict
+exec_url:
+  description: |
+    The URL to start an exec instance.
+  in: body
+  type: dict
 forced_down:
   description: |
     Whether or not this service was forced down manually by an

api-ref/source/samples/container-execute-resp-2.json

@@ -0,0 +1,4 @@
+{
+    "url": "tcp://172.16.1.45:2375",
+    "exec_id": "3c851c568fc9f21bdb77b7ba98eb1c6ae0c901f56dfb1471de4d6af7c73dbf4d"
+}

api-ref/source/samples/container-execute-resp.json

@@ -0,0 +1,4 @@
+{
+    "output": "Mon Oct  9 09:09:32 UTC 2017\n",
+    "exit_code": 0
+}