Add Swagger UI for dovetail API

Change-Id: If8f515b02f0372955739dd580967a3198930e98b
Signed-off-by: xudan <xudan16@huawei.com>

diff --git a/docker/Dockerfile b/docker/Dockerfile
index 077f5e3..56ca1ea 100644 (file)
--- 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 (file)
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 (file)
--- 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 (file)
--- 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 (executable)
--- 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 (file)
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 (file)
--- 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