summaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide
diff options
context:
space:
mode:
authorxudan <xudan16@huawei.com>2019-06-27 04:37:55 -0400
committerDan Xu <xudan16@huawei.com>2019-07-10 03:09:06 +0000
commit1f36d6247578273197a4ba64b58b02b1ed837171 (patch)
treea8049bb2a3523c678ff16741cf754993fd8e9fd5 /docs/testing/user/userguide
parent1aafeb7eeef0a870d0c4cef95c929b66fd8ad991 (diff)
Add Swagger UI for dovetail API
Change-Id: If8f515b02f0372955739dd580967a3198930e98b Signed-off-by: xudan <xudan16@huawei.com>
Diffstat (limited to 'docs/testing/user/userguide')
-rw-r--r--docs/testing/user/userguide/api_testing_guide.rst114
-rw-r--r--docs/testing/user/userguide/index.rst1
2 files changed, 115 insertions, 0 deletions
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