Merge "Add api-ref for container top"

api-ref/source/containers.inc

@@ -6,7 +6,8 @@
 
 Lists, creates, shows details for, stats, updates, deletes, starts, resize,
 stops, pauses, unpauses, restarts, renames, commits containers, and adds
-security group for specified container, gets logs of a container.
+security group for specified container, gets logs of a container, displays
+the running processes in a container.
 
 Create new container
 ====================
@@ -865,3 +866,46 @@ Response
 
 This request returns logs string as a response, which is
 not in json format.
+
+
+Display the running processes in a container
+============================================
+
+.. rest_method:: GET /v1/containers/{container_ident}/top?ps_args={ps_args}
+
+Display the running processes in a 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
+   - ps_args: ps_args
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - ps_output: ps_output
+
+Response Example
+----------------
+
+.. literalinclude:: samples/container-top-resp.json
+   :language: javascript

api-ref/source/parameters.yaml

@@ -41,6 +41,12 @@ new_name:
   in: query
   required: true
   type: string
+ps_args:
+  description: |
+    The arguments of ps command.
+  in: query
+  required: false
+  type: string
 repository:
   description: |
     The reposiroty of the container image.
@@ -282,6 +288,12 @@ ports:
   in: body
   required: true
   type: string
+ps_output:
+  description: |
+    The output of zun top.
+  in: body
+  required: true
+  type: dict
 report_count:
   description: |
     The total number of report.

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

@@ -0,0 +1,16 @@
+{
+    "Processes": [
+        ["root", "28363", "28344", "0", "Sep28", "pts/0", "00:00:00", "nginx: master process nginx -g daemon off;"],
+        ["systemd+", "28436", "28363", "0", "Sep28", "pts/0", "00:00:00", "nginx: worker process"]
+    ],
+    "Titles": [
+        "UID",
+        "PID",
+        "PPID",
+        "C",
+        "STIME",
+        "TTY",
+        "TIME",
+        "CMD"
+    ]
+}