diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/testing/user/userguide/api_testing_guide.rst | 114 | ||||
| -rw-r--r-- | docs/testing/user/userguide/index.rst | 1 |
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 |