From 1f36d6247578273197a4ba64b58b02b1ed837171 Mon Sep 17 00:00:00 2001
From: xudan <xudan16@huawei.com>
Date: Thu, 27 Jun 2019 04:37:55 -0400
Subject: Add Swagger UI for dovetail API

Change-Id: If8f515b02f0372955739dd580967a3198930e98b
Signed-off-by: xudan <xudan16@huawei.com>
---
 docs/testing/user/userguide/api_testing_guide.rst | 114 ++++++++++++++++++++++
 docs/testing/user/userguide/index.rst             |   1 +
 2 files changed, 115 insertions(+)
 create mode 100644 docs/testing/user/userguide/api_testing_guide.rst

(limited to 'docs/testing')

diff --git a/docs/testing/user/userguide/api_testing_guide.rst b/docs/testing/user/userguide/api_testing_guide.rst
new file mode 100644
index 00000000..edcb4329
--- /dev/null
+++ b/docs/testing/user/userguide/api_testing_guide.rst
@@ -0,0 +1,114 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Huawei Technologies Co.,Ltd and others.
+
+===============================
+Running Dovetail by RESTful API
+===============================
+
+Overview
+--------
+
+Dovetail framework provides RESTful APIs for end users to run all OVP test cases.
+Also it provides a Swagger UI for users to find out all APIs and try them out.
+
+
+Definitions and abbreviations
+-----------------------------
+
+- REST - Representational State Transfer
+- API - Application Programming Interface
+- OVP - OPNFV Verification Program
+- UI - User Interface
+
+
+Environment Preparation
+-----------------------
+
+
+Install Docker
+^^^^^^^^^^^^^^
+
+The main prerequisite software for Dovetail is Docker. Please refer to `official
+Docker installation guide <https://docs.docker.com/install/>`_ which is relevant
+to your Test Host's operating system.
+
+
+Configuring the Test Host Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For convenience and as a convention, we will create a home directory for storing
+all Dovetail related config items and results files:
+
+.. code-block:: bash
+
+   $ mkdir -p ${HOME}/dovetail
+   $ export DOVETAIL_HOME=${HOME}/dovetail
+
+
+Installing Dovetail API
+-----------------------
+
+The Dovetail project maintains a Docker image that has both Dovetail API and
+Dovetail CLI preinstalled. This Docker image is tagged with versions.
+Before pulling the Dovetail image, check the OPNFV's OVP web page first to
+determine the right tag for OVP testing.
+
+
+Downloading Dovetail Docker Image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first version of Dovetail API is ovp-3.x.x.
+
+.. code-block:: bash
+
+   $ sudo docker pull opnfv/dovetail:latest
+   latest: Pulling from opnfv/dovetail
+   6abc03819f3e: Pull complete
+   05731e63f211: Pull complete
+   0bd67c50d6be: Pull complete
+   3f737f5d00b2: Pull complete
+   c93fd0792ebd: Pull complete
+   77d9a9603ec6: Pull complete
+   9463cdd9c628: Pull complete
+   Digest: sha256:45e2ffdbe217a4e6723536afb5b6a3785d318deff535da275f34cf8393af458d
+   Status: Downloaded newer image for opnfv/dovetail:latest
+
+
+Deploying Dovetail API
+^^^^^^^^^^^^^^^^^^^^^^
+
+The Dovetail API can be deployed by running a Dovetail container with the Docker
+image downloaded before.
+
+.. code-block:: bash
+
+   $ docker run -itd -p <swagger_port>:80 -p <api_port>:5000 --privileged=true \
+     -e SWAGGER_HOST=<host_ip>:<swagger_port> -e DOVETAIL_HOME=/home/ovp \
+     -v /home/ovp:/home/ovp -v /var/run/docker.sock:/var/run/docker.sock \
+     opnfv/dovetail:<version>
+
+
+In the container, it uses 2 ports for Swagger UI (port 80) and API (port 5000)
+respectively. So in order to access to these 2 services outside the container,
+it needs to map them to the host ports. It can be any available ports in the host.
+
+The env SWAGGER_HOST is optional. If you will access the Swagger UI webpage with
+the same host deploying this container, there is no need to set SWAGGER_HOST.
+Otherwise, if you will access the Swagger UI webpage from other machines, then
+it needs to set SWAGGER_HOST.
+
+
+Using Dovetail API
+------------------
+
+Here give the guide of where to find out all APIs and how to use them.
+
+
+Swagger UI Webpage
+^^^^^^^^^^^^^^^^^^
+
+After deploying Dovetail container, the Swagger UI webpage can be accessed with
+any browser. The url is `http://localhost:<swagger_port>/dovetail-api/index.html`
+if accessing from the same host as deploying this container. Otherwise, the url
+is `http://<host_ip>:<swagger_port>/dovetail-api/index.html`.
diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst
index 68e9f1f8..f35e2927 100644
--- a/docs/testing/user/userguide/index.rst
+++ b/docs/testing/user/userguide/index.rst
@@ -14,3 +14,4 @@ OVP Testing User Guide
    testing_guide.rst
    cli_reference.rst
    vnf_test_guide.rst
+   api_testing_guide.rst
-- 
cgit 1.2.3-korg