From 1f36d6247578273197a4ba64b58b02b1ed837171 Mon Sep 17 00:00:00 2001 From: xudan Date: Thu, 27 Jun 2019 04:37:55 -0400 Subject: Add Swagger UI for dovetail API Change-Id: If8f515b02f0372955739dd580967a3198930e98b Signed-off-by: xudan --- docker/Dockerfile | 12 ++- docs/testing/user/userguide/api_testing_guide.rst | 114 ++++++++++++++++++++++ docs/testing/user/userguide/index.rst | 1 + dovetail/api/app/routes.py | 2 + dovetail/api/boot.sh | 12 +++ dovetail/api/swagger.yaml | 54 ++++++++++ requirements.txt | 1 + 7 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 docs/testing/user/userguide/api_testing_guide.rst create mode 100644 dovetail/api/swagger.yaml diff --git a/docker/Dockerfile b/docker/Dockerfile index 077f5e34..56ca1ea2 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -12,11 +12,13 @@ MAINTAINER Stamatis Katsaounis 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 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 `_ 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 :80 -p :5000 --privileged=true \ + -e SWAGGER_HOST=: -e DOVETAIL_HOME=/home/ovp \ + -v /home/ovp:/home/ovp -v /var/run/docker.sock:/var/run/docker.sock \ + opnfv/dovetail: + + +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:/dovetail-api/index.html` +if accessing from the same host as deploying this container. Otherwise, the url +is `http://:/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 diff --git a/dovetail/api/app/routes.py b/dovetail/api/app/routes.py index c235cb48..6c327323 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 dc49876a..9fbb5484 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 00000000..5df0dcc2 --- /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 ae2aff1e..4e6b808d 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 -- cgit 1.2.3-korg