summaryrefslogtreecommitdiffstats
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
parent1aafeb7eeef0a870d0c4cef95c929b66fd8ad991 (diff)
Add Swagger UI for dovetail API
Change-Id: If8f515b02f0372955739dd580967a3198930e98b Signed-off-by: xudan <xudan16@huawei.com>
-rw-r--r--docker/Dockerfile12
-rw-r--r--docs/testing/user/userguide/api_testing_guide.rst114
-rw-r--r--docs/testing/user/userguide/index.rst1
-rw-r--r--dovetail/api/app/routes.py2
-rwxr-xr-xdovetail/api/boot.sh12
-rw-r--r--dovetail/api/swagger.yaml54
-rw-r--r--requirements.txt1
7 files changed, 195 insertions, 1 deletions
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 077f5e3..56ca1ea 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -12,11 +12,13 @@ MAINTAINER Stamatis Katsaounis <mokats@intracom-telecom.com>
LABEL version="0.1" description="OPNFV Dovetail Docker Container"
ARG BRANCH=master
+ARG SWAGGER_UI_TAG=v3.22.3
RUN \
apt-get update \
&& \
apt-get install -y \
+ apache2 \
gcc \
make \
git \
@@ -50,8 +52,16 @@ RUN \
&& \
ln -s /usr/local/lib/python2.7/dist-packages/dovetail ${REPOS_DIR}/dovetail
+RUN \
+ git clone https://github.com/swagger-api/swagger-ui.git \
+&& \
+ cd swagger-ui && git checkout $SWAGGER_UI_TAG
+
WORKDIR ${REPOS_DIR}/dovetail
ENV FLASK_APP ${API_DIR}/app/routes.py
+# This port is for flask API in container
EXPOSE 5000
-CMD ${API_DIR}/boot.sh
+# This port is for Swagger UI in container
+EXPOSE 80
+CMD bash ${API_DIR}/boot.sh
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 0000000..edcb432
--- /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 68e9f1f..f35e292 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
diff --git a/dovetail/api/app/routes.py b/dovetail/api/app/routes.py
index c235cb4..6c32732 100644
--- a/dovetail/api/app/routes.py
+++ b/dovetail/api/app/routes.py
@@ -1,10 +1,12 @@
#!flask/bin/python
from flask import Flask, jsonify
+from flask_cors import CORS
import server
app = Flask(__name__)
+CORS(app)
@app.route('/api/v1/scenario/nfvi/testsuites', methods=['GET'])
diff --git a/dovetail/api/boot.sh b/dovetail/api/boot.sh
index dc49876..9fbb548 100755
--- a/dovetail/api/boot.sh
+++ b/dovetail/api/boot.sh
@@ -1,4 +1,16 @@
#!/bin/sh
+mkdir -p /var/www/html/dovetail-api
+cp -r /home/opnfv/swagger-ui/dist/* /var/www/html/dovetail-api
+cp /home/opnfv/dovetail/dovetail/api/swagger.yaml /var/www/html/dovetail-api
+sed -i 's#url: "https://petstore.swagger.io/v2/swagger.json"#url: "swagger.yaml"#g' /var/www/html/dovetail-api/index.html
+sed -i '/deepLinking: true,/a\ validatorUrl: null,' /var/www/html/dovetail-api/index.html
+
+if [[ -n ${SWAGGER_HOST} ]]; then
+ sed -i "s/host: localhost:8888/host: ${SWAGGER_HOST}/g" /var/www/html/dovetail-api/swagger.yaml
+fi
+
+/etc/init.d/apache2 start
+
cd $(dirname $(readlink -f $0))
exec gunicorn -b :5000 --access-logfile - --error-logfile - app.routes:app
diff --git a/dovetail/api/swagger.yaml b/dovetail/api/swagger.yaml
new file mode 100644
index 0000000..5df0dcc
--- /dev/null
+++ b/dovetail/api/swagger.yaml
@@ -0,0 +1,54 @@
+swagger: "2.0"
+info:
+ description: "This is the dovetail API."
+ version: "1.0.0"
+ title: "Dovetail API"
+ contact:
+ email: "xudan16@huawei.com"
+ license:
+ name: "Apache 2.0"
+ url: "http://www.apache.org/licenses/LICENSE-2.0.html"
+host: localhost:8888
+basePath: "/api/v1/scenario/nfvi"
+tags:
+- name: "testsuites"
+ description: "Operations about testsuites"
+- name: "testcases"
+ description: "Operations about test cases"
+schemes:
+- "http"
+paths:
+ /testsuites:
+ get:
+ tags:
+ - "testsuites"
+ summary: "Get all testsuites"
+ description: ""
+ operationId: "getTestsuites"
+ consumes:
+ - "application/json"
+ produces:
+ - "application/json"
+ parameters: []
+ responses:
+ 200:
+ description: "successful operation"
+ default:
+ description: Unexpected error
+ /testcases:
+ get:
+ tags:
+ - "testcases"
+ summary: "Get all test cases"
+ description: ""
+ operationId: "getTestcases"
+ consumes:
+ - "application/json"
+ produces:
+ - "application/json"
+ parameters: []
+ responses:
+ 200:
+ description: "successful operation"
+ default:
+ description: Unexpected error
diff --git a/requirements.txt b/requirements.txt
index ae2aff1..4e6b808 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -11,6 +11,7 @@ ansible==2.2.0
click==6.7
docker==3.4.1
flask==1.0.2
+flask-cors==3.0.8
gunicorn==19.9.0
Jinja2==2.10
os-client-config==1.29.0