From df847cc1405891edd9e2b20092f6d48e6f3f6e6d Mon Sep 17 00:00:00 2001
From: miaohb <miao.hongbao@zte.com.cn>
Date: Sun, 15 Oct 2017 23:46:59 -0700
Subject: [PATCH] Add api-ref for container top

This patch adds api-ref for container top.

Change-Id: I3f548a63afe15fe78ac07e9d61e0987b43677932
Closes-Bug: #1720929
---
 api-ref/source/containers.inc                 | 46 ++++++++++++++++++-
 api-ref/source/parameters.yaml                | 12 +++++
 .../source/samples/container-top-resp.json    | 16 +++++++
 3 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 api-ref/source/samples/container-top-resp.json

diff --git a/api-ref/source/containers.inc b/api-ref/source/containers.inc
index 78000bd83..d2fb49a60 100644
--- a/api-ref/source/containers.inc
+++ b/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
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index b54b4cd45..8ccfa980d 100644
--- a/api-ref/source/parameters.yaml
+++ b/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.
diff --git a/api-ref/source/samples/container-top-resp.json b/api-ref/source/samples/container-top-resp.json
new file mode 100644
index 000000000..7fd0d9cad
--- /dev/null
+++ b/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"
+    ]
+}