Add swagger support for Rest API

JIRA: FUNCTEST-854

Change-Id: Ic010604d3ba0cc46092cf2a1ae8bb41afa73c920
Signed-off-by: Linda Wang <wangwulin@huawei.com>
(cherry picked from commit b621b6b4b70299a60ad3e26ed6b04450f84b603e)

20 files changed, 477 insertions, 0 deletions

diff --git a/functest/api/resources/v1/creds.py b/functest/api/resources/v1/creds.py
index 45e4559f4..f445017dc 100644
--- a/functest/api/resources/v1/creds.py
+++ b/functest/api/resources/v1/creds.py
@@ -13,8 +13,11 @@ Resources to handle openstack related requests
 
 import collections
 import logging
+import pkg_resources
+import socket
 
 from flask import jsonify
+from flasgger.utils import swag_from
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils
@@ -24,16 +27,26 @@ from functest.utils.constants import CONST
 
 LOGGER = logging.getLogger(__name__)
 
+ADDRESS = socket.gethostbyname(socket.gethostname())
+ENDPOINT_CREDS = ('http://{}:5000/api/v1/functest/openstack'.format(ADDRESS))
+
 
 class V1Creds(ApiResource):
     """ V1Creds Resource class"""
 
+    @swag_from(
+        pkg_resources.resource_filename('functest', 'api/swagger/creds.yaml'),
+        endpoint='{0}/credentials'.format(ENDPOINT_CREDS))
     def get(self):  # pylint: disable=no-self-use
         """ Get credentials """
         os_utils.source_credentials(CONST.__getattribute__('openstack_creds'))
         credentials_show = OpenStack.show_credentials()
         return jsonify(credentials_show)
 
+    @swag_from(
+        pkg_resources.resource_filename('functest',
+                                        'api/swagger/creds_action.yaml'),
+        endpoint='{0}/action'.format(ENDPOINT_CREDS))
     def post(self):
         """ Used to handle post request """
         return self._dispatch_post()
diff --git a/functest/api/resources/v1/envs.py b/functest/api/resources/v1/envs.py
index 8020544fb..65e61c4ba 100644
--- a/functest/api/resources/v1/envs.py
+++ b/functest/api/resources/v1/envs.py
@@ -10,23 +10,37 @@
 Resources to handle environment related requests
 """
 
+import pkg_resources
+import socket
+
 import IPy
 from flask import jsonify
+from flasgger.utils import swag_from
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils
 from functest.cli.commands.cli_env import Env
 import functest.utils.functest_utils as ft_utils
 
+ADDRESS = socket.gethostbyname(socket.gethostname())
+ENDPOINT_ENVS = ('http://{}:5000/api/v1/functest/envs'.format(ADDRESS))
+
 
 class V1Envs(ApiResource):
     """ V1Envs Resource class"""
 
+    @swag_from(
+        pkg_resources.resource_filename('functest', 'api/swagger/envs.yaml'),
+        endpoint=ENDPOINT_ENVS)
     def get(self):  # pylint: disable=no-self-use
         """ Get environment """
         environment_show = Env().show()
         return jsonify(environment_show)
 
+    @swag_from(
+        pkg_resources.resource_filename('functest',
+                                        'api/swagger/envs_action.yaml'),
+        endpoint='{0}/action'.format(ENDPOINT_ENVS))
     def post(self):
         """ Used to handle post request """
         return self._dispatch_post()
diff --git a/functest/api/resources/v1/tasks.py b/functest/api/resources/v1/tasks.py
index 492141249..6bf625a88 100644
--- a/functest/api/resources/v1/tasks.py
+++ b/functest/api/resources/v1/tasks.py
@@ -15,9 +15,11 @@ import errno
 import json
 import logging
 import os
+import pkg_resources
 import uuid
 
 from flask import jsonify
+from flasgger.utils import swag_from
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils
@@ -31,6 +33,8 @@ LOGGER = logging.getLogger(__name__)
 class V1Task(ApiResource):
     """ V1Task Resource class"""
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/task.yaml'))
     def get(self, task_id):  # pylint: disable=no-self-use
         """ GET the result of the task id """
         try:
@@ -66,6 +70,8 @@ class V1Task(ApiResource):
 class V1TaskLog(ApiResource):
     """ V1TaskLog Resource class"""
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/task_log.yaml'))
     def get(self, task_id):  # pylint: disable=no-self-use
         """ GET the log of the task id """
         try:
diff --git a/functest/api/resources/v1/testcases.py b/functest/api/resources/v1/testcases.py
index cc2d4e193..b67331377 100644
--- a/functest/api/resources/v1/testcases.py
+++ b/functest/api/resources/v1/testcases.py
@@ -14,10 +14,12 @@ Resources to handle testcase related requests
 import logging
 import os
 import pkg_resources
+import socket
 import uuid
 
 import ConfigParser
 from flask import jsonify
+from flasgger.utils import swag_from
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils, thread
@@ -28,10 +30,16 @@ import functest.utils.functest_utils as ft_utils
 
 LOGGER = logging.getLogger(__name__)
 
+ADDRESS = socket.gethostbyname(socket.gethostname())
+ENDPOINT_TESTCASES = ('http://{}:5000/api/v1/functest/testcases'
+                      .format(ADDRESS))
+
 
 class V1Testcases(ApiResource):
     """ V1Testcases Resource class"""
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/testcases.yaml'))
     def get(self):  # pylint: disable=no-self-use
         """ GET all testcases """
         testcases_list = Testcase().list()
@@ -42,6 +50,10 @@ class V1Testcases(ApiResource):
 class V1Testcase(ApiResource):
     """ V1Testcase Resource class"""
 
+    @swag_from(
+        pkg_resources.resource_filename('functest',
+                                        'api/swagger/testcase.yaml'),
+        endpoint='{0}/<testcase_name>'.format(ENDPOINT_TESTCASES))
     def get(self, testcase_name):  # pylint: disable=no-self-use
         """ GET the info of one testcase"""
         testcase = Testcase().show(testcase_name)
@@ -61,6 +73,10 @@ class V1Testcase(ApiResource):
         result.update({'dependency': dependency_dict})
         return jsonify(result)
 
+    @swag_from(
+        pkg_resources.resource_filename('functest',
+                                        'api/swagger/testcase_run.yaml'),
+        endpoint='{0}/action'.format(ENDPOINT_TESTCASES))
     def post(self):
         """ Used to handle post request """
         return self._dispatch_post()
diff --git a/functest/api/resources/v1/tiers.py b/functest/api/resources/v1/tiers.py
index b58ab205e..523df130e 100644
--- a/functest/api/resources/v1/tiers.py
+++ b/functest/api/resources/v1/tiers.py
@@ -11,9 +11,11 @@
 Resources to handle tier related requests
 """
 
+import pkg_resources
 import re
 
 from flask import jsonify
+from flasgger.utils import swag_from
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils
@@ -23,6 +25,8 @@ from functest.cli.commands.cli_tier import Tier
 class V1Tiers(ApiResource):
     """ V1Tiers Resource class """
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/tiers.yaml'))
     def get(self):
         # pylint: disable=no-self-use
         """ GET all tiers """
@@ -43,6 +47,8 @@ class V1Tiers(ApiResource):
 class V1Tier(ApiResource):
     """ V1Tier Resource class """
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/tier.yaml'))
     def get(self, tier_name):  # pylint: disable=no-self-use
         """ GET the info of one tier """
         tier_info = Tier().show(tier_name)
@@ -62,6 +68,8 @@ class V1Tier(ApiResource):
 class V1TestcasesinTier(ApiResource):
     """ V1TestcasesinTier Resource class """
 
+    @swag_from(pkg_resources.resource_filename(
+        'functest', 'api/swagger/testcases_in_tier.yaml'))
     def get(self, tier_name):  # pylint: disable=no-self-use
         """ GET all testcases within given tier """
         tier_info = Tier().show(tier_name)
diff --git a/functest/api/server.py b/functest/api/server.py
index c6eb0b3ba..3200c1a2f 100644
--- a/functest/api/server.py
+++ b/functest/api/server.py
@@ -20,6 +20,7 @@ import pkg_resources
 
 from flask import Flask
 from flask_restful import Api
+from flasgger import Swagger
 
 from functest.api.base import ApiResource
 from functest.api.common import api_utils
@@ -34,6 +35,7 @@ LOGGER = logging.getLogger(__name__)
 
 APP = Flask(__name__)
 API = Api(APP)
+Swagger(APP)
 
 
 @APP.teardown_request
diff --git a/functest/api/swagger/creds.yaml b/functest/api/swagger/creds.yaml
new file mode 100644
index 000000000..da3b2d900
--- /dev/null
+++ b/functest/api/swagger/creds.yaml
@@ -0,0 +1,35 @@
+Show credentials
+
+This api offers the interface to show credentials.
+The credentials dict will be returned.
+---
+tags:
+  - Creds
+definitions:
+  Credentials:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Name'
+  Name:
+    type: dict
+responses:
+  200:
+    description: Show credentials
+    schema:
+      $ref: '#/definitions/Credentials'
+    examples:
+      "OS_AUTH_URL": "https://192.16.1.222:5000/v3"
+      "OS_AUTH_VERSION": "3"
+      "OS_CACERT": "/home/opnfv/functest/conf/os_cacert"
+      "OS_ENDPOINT_TYPE": "publicURL"
+      "OS_IDENTITY_API_VERSION": "3"
+      "OS_INTERFACE": "publicURL"
+      "OS_NO_CACHE": "1"
+      "OS_PASSWORD": "990232e0885da343ac805528522d"
+      "OS_PROJECT_DOMAIN_NAME": "Default"
+      "OS_PROJECT_NAME": "admin"
+      "OS_REGION_NAME": "RegionOne"
+      "OS_TENANT_NAME": "admin"
+      "OS_USERNAME": "admin"
+      "OS_USER_DOMAIN_NAME": "Default"
diff --git a/functest/api/swagger/creds_action.yaml b/functest/api/swagger/creds_action.yaml
new file mode 100644
index 000000000..d67d082da
--- /dev/null
+++ b/functest/api/swagger/creds_action.yaml
@@ -0,0 +1,57 @@
+Update openrc
+
+This api offers the interface to Update openstack.creds.
+
+action: update_openrc
+---
+tags:
+  - Creds
+parameters:
+  - in: body
+    name: body
+    description: this is the input json dict
+    schema:
+      required:
+        - action
+        - args
+      properties:
+        action:
+          type: string
+          description: this is action for creds
+          default: update_openrc
+        args:
+          schema:
+            required:
+              - openrc
+            properties:
+              openrc:
+                type: string
+                description: this is the test case name
+                default:
+                  "OS_AUTH_URL": "http://192.16.1.222:5000/v3"
+                  "OS_ENDPOINT_TYPE": "publicURL"
+                  "OS_IDENTITY_API_VERSION": "3"
+                  "OS_INTERFACE": "publicURL"
+                  "OS_PASSWORD": "admn"
+                  "OS_PROJECT_DOMAIN_NAME": "Default"
+                  "OS_PROJECT_NAME": "admin"
+                  "OS_REGION_NAME": "RegionOne"
+                  "OS_TENANT_NAME": "admin"
+                  "OS_USERNAME": "admin"
+                  "OS_USER_DOMAIN_NAME": "Default"
+definitions:
+  Credentials:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Name'
+  Name:
+    type: dict
+responses:
+  200:
+    description: Update openrc
+    schema:
+      $ref: '#/definitions/Credentials'
+    examples:
+      'status': 0
+      'result': 'Update openrc successfully'
diff --git a/functest/api/swagger/envs.yaml b/functest/api/swagger/envs.yaml
new file mode 100644
index 000000000..e723deb3f
--- /dev/null
+++ b/functest/api/swagger/envs.yaml
@@ -0,0 +1,26 @@
+Show environment
+
+This api offers the interface to show environment.
+The environment dict will be returned.
+---
+tags:
+  - Envs
+definitions:
+  Environment:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Name'
+  Name:
+    type: dict
+responses:
+  200:
+    description: Show environment
+    schema:
+      $ref: '#/definitions/Environment'
+    examples:
+      "DEBUG FLAG": "false"
+      "INSTALLER": "compass, 192.168.200.2"
+      "POD": "unknown_pod"
+      "SCENARIO": "os-nosdn-nofeature-noha"
+      "STATUS": "ready"
diff --git a/functest/api/swagger/envs_action.yaml b/functest/api/swagger/envs_action.yaml
new file mode 100644
index 000000000..1add066ee
--- /dev/null
+++ b/functest/api/swagger/envs_action.yaml
@@ -0,0 +1,37 @@
+Prepare environment or Update hosts info
+
+This api offers the interface to prepare environment or update hosts info.
+
+action: prepare
+action: update_hosts
+---
+tags:
+  - Envs
+parameters:
+  - in: body
+    name: body
+    description: this is the input json dict
+    schema:
+      required:
+        - action
+      properties:
+        action:
+          type: string
+          description: this is action for envs
+          default: prepare
+definitions:
+  Environment:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Name'
+  Name:
+    type: dict
+responses:
+  200:
+    description: Prepare environment
+    schema:
+      $ref: '#/definitions/Environment'
+    examples:
+      'status': 0
+      'result': 'Prapare env successfully'
diff --git a/functest/api/swagger/task.yaml b/functest/api/swagger/task.yaml
new file mode 100644
index 000000000..abf68a0d6
--- /dev/null
+++ b/functest/api/swagger/task.yaml
@@ -0,0 +1,38 @@
+Get the result of the specified task
+
+This api offers the interface to get the result of the specified task.
+
+---
+tags:
+  - Tasks
+parameters:
+  - name: task_id
+    description: task id
+    in: path
+    type: string
+    required: true
+definitions:
+  Task:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Result'
+  Result:
+    type: dict
+responses:
+  200:
+    description: Get the result of the specified task
+    schema:
+      $ref: '#/definitions/Task'
+    examples:
+      "result": {
+        "case_name": "vping_ssh",
+        "env_info": {
+            "build_tag": null,
+            "ci_loop": "weekly",
+            "installer": "compass",
+            "scenario": "os-nosdn-nofeature-noha" },
+        "result": "PASS",
+        "task_id": "1a9f3c5d-ce0b-4354-862e-dd08b26fc484"}
+      "status": 2
+
diff --git a/functest/api/swagger/task_log.yaml b/functest/api/swagger/task_log.yaml
new file mode 100644
index 000000000..adaaaf407
--- /dev/null
+++ b/functest/api/swagger/task_log.yaml
@@ -0,0 +1,35 @@
+Get the log of the specified task
+
+This api offers the interface to get the log of the specified task.
+
+---
+tags:
+  - Tasks
+parameters:
+  - name: task_id
+    description: task id
+    in: path
+    type: string
+    required: true
+definitions:
+  Task:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Result'
+  Result:
+    type: dict
+responses:
+  200:
+    description: Get the log of the specified task
+    schema:
+      $ref: '#/definitions/Task'
+    examples:
+      "result": {
+        "data": [
+        "2017-09-14 06:46:26,106 - functest.ci.run_tests - DEBUG - Sourcing the OpenStack RC file... ",
+        "2017-09-14 06:46:26,107 - functest.ci.run_tests - DEBUG - Test args: connection_check ",
+        "2017-09-14 06:46:26,107 - functest.ci.run_tests - INFO - Running test case 'connection_check'... ",
+        "..."]}
+      "status": 2
+
diff --git a/functest/api/swagger/testcase.yaml b/functest/api/swagger/testcase.yaml
new file mode 100644
index 000000000..70ee1af1a
--- /dev/null
+++ b/functest/api/swagger/testcase.yaml
@@ -0,0 +1,36 @@
+Show the info of one testcase
+
+This api offers the interface to show the detailed info of one testcase.
+The info of one testcase will be returned.
+---
+tags:
+  - Testcases
+parameters:
+  - name: testcase_name
+    description: testcase name
+    in: path
+    type: string
+    required: true
+definitions:
+  Testcases:
+    type: object
+    properties:
+      case_name:
+          $ref: '#/definitions/Tests'
+  Tests:
+    type: dict
+responses:
+  200:
+    description: Show the detailed info of one testcase
+    schema:
+      $ref: '#/definitions/Testcases'
+    examples:
+        "testcase": ""
+        "blocking":
+        "criteria":
+        "dependency": {
+            "installer": "",
+            "scenario": ""
+        }
+        "description": ""
+        "enabled":
diff --git a/functest/api/swagger/testcase_run.yaml b/functest/api/swagger/testcase_run.yaml
new file mode 100644
index 000000000..d451457d1
--- /dev/null
+++ b/functest/api/swagger/testcase_run.yaml
@@ -0,0 +1,47 @@
+Run a test case
+
+This api offers the interface to run a test case
+
+action: run_test_case
+---
+tags:
+  - Testcases
+parameters:
+  - in: body
+    name: body
+    description: this is the input json dict
+    schema:
+      required:
+        - action
+        - args
+      properties:
+        action:
+          type: string
+          description: this is action for creds
+          default: run_test_case
+        args:
+          schema:
+            required:
+              - testcase
+            properties:
+              testcase:
+                type: string
+                description: this is the test case name
+                default:
+                  vping_ssh
+definitions:
+  Testcases:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Tests'
+  Tests:
+    type: dict
+responses:
+  200:
+    description: Run a test case
+    schema:
+      $ref: '#/definitions/Testcases'
+    examples:
+      'task_id': '94c8ec94-d873-466f-a205-bf592f31ff5b'
+      'testcase': 'vping_ssh'
diff --git a/functest/api/swagger/testcases.yaml b/functest/api/swagger/testcases.yaml
new file mode 100644
index 000000000..56d9d71f4
--- /dev/null
+++ b/functest/api/swagger/testcases.yaml
@@ -0,0 +1,22 @@
+List all test cases
+
+This api offers the interface to list all test cases
+The testcases list will be returned
+---
+tags:
+  - Testcases
+definitions:
+  Testcases:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Tests'
+  Tests:
+    type: dict
+responses:
+  200:
+    description: List all test cases
+    schema:
+      $ref: '#/definitions/Testcases'
+    examples:
+      "testcases": []
diff --git a/functest/api/swagger/testcases_in_tier.yaml b/functest/api/swagger/testcases_in_tier.yaml
new file mode 100644
index 000000000..f64508264
--- /dev/null
+++ b/functest/api/swagger/testcases_in_tier.yaml
@@ -0,0 +1,29 @@
+List all testcases within given tier
+
+This api offers the interface to list all testcases within given tier.
+All testcases within given tier will be returned.
+---
+tags:
+  - Tiers
+parameters:
+  - name: tier_name
+    description: tier name
+    in: path
+    type: string
+    required: true
+definitions:
+  Testcases:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Tests'
+  Tests:
+    type: dict
+responses:
+  200:
+    description: List all testcases within given tier
+    schema:
+      $ref: '#/definitions/Testcases'
+    examples:
+        "tier": ""
+        "testcases": []
diff --git a/functest/api/swagger/tier.yaml b/functest/api/swagger/tier.yaml
new file mode 100644
index 000000000..8616afb5f
--- /dev/null
+++ b/functest/api/swagger/tier.yaml
@@ -0,0 +1,32 @@
+Show the info of one tier
+
+This api offers the interface to show the detailed info of one tier.
+The info of one tier will be returned.
+---
+tags:
+  - Tiers
+parameters:
+  - name: tier_name
+    description: tier name
+    in: path
+    type: string
+    required: true
+definitions:
+  Tiers:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Name'
+  Name:
+    type: string
+responses:
+  200:
+    description: Show the detailed info of one tier
+    schema:
+      $ref: '#/definitions/Tiers'
+    examples:
+        "tier": ""
+        "ci_loop": ""
+        "description": ""
+        "order":
+        "testcases": []
diff --git a/functest/api/swagger/tiers.yaml b/functest/api/swagger/tiers.yaml
new file mode 100644
index 000000000..8a71c3798
--- /dev/null
+++ b/functest/api/swagger/tiers.yaml
@@ -0,0 +1,22 @@
+List all tiers
+
+This api offers the interface to list all tiers.
+The tiers list will be returned.
+---
+tags:
+  - Tiers
+definitions:
+  Tiers:
+    type: object
+    properties:
+      creds_name:
+          $ref: '#/definitions/Tier'
+  Tier:
+    type: dict
+responses:
+  200:
+      description: List all tiers
+      schema:
+          $ref: '#/definitions/Tiers'
+      examples:
+          "tiers": ""
diff --git a/requirements.txt b/requirements.txt
index 650f61458..d4a0377dd 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -22,6 +22,7 @@ cloudify-rest-client
 Flask!=0.11,<1.0,>=0.10 # BSD
 Flask-RESTful>=0.3.5 # BSD
 IPy
+flasgger # MIT
 mock>=2.0 # BSD
 iniparse==0.4
 PrettyTable<0.8,>=0.7.1 # BSD
diff --git a/upper-constraints.txt b/upper-constraints.txt
index f24960789..049424e0d 100644
--- a/upper-constraints.txt
+++ b/upper-constraints.txt
@@ -16,3 +16,4 @@ robotframework-sshlibrary===2.1.3;python_version=='2.7'
 IPy===0.83
 os-faults===0.1.10
 ansible===2.3.2.0
+flasgger===0.6.6