Add swagger support for Rest API

JIRA: YARDSTICK-439

Change-Id: I36ad0663455c51d635c4329f5cbb9da25d8042e1
Signed-off-by: chenjiankun <chenjiankun1@huawei.com>

7 files changed, 162 insertions, 0 deletions

diff --git a/api/server.py b/api/server.py
index 3f104c61a..64a2b4f96 100644
--- a/api/server.py
+++ b/api/server.py
@@ -10,6 +10,7 @@ import logging
 
 from flask import Flask
 from flask_restful import Api
+from flasgger import Swagger
 
 from api.urls import urlpatterns
 from yardstick import _init_logging
@@ -18,8 +19,11 @@ logger = logging.getLogger(__name__)
 
 app = Flask(__name__)
 
+Swagger(app)
+
 api = Api(app)
 
+
 reduce(lambda a, b: a.add_resource(b.resource, b.url,
                                    endpoint=b.endpoint) or a, urlpatterns, api)
 
diff --git a/api/swagger/__init__.py b/api/swagger/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/api/swagger/__init__.py
diff --git a/api/swagger/docs/results.yaml b/api/swagger/docs/results.yaml
new file mode 100644
index 000000000..7bdab3eb6
--- /dev/null
+++ b/api/swagger/docs/results.yaml
@@ -0,0 +1,41 @@
+Query task result data
+
+This api offer the interface to get the result data via task_id
+We will return a result json dict
+---
+tags:
+  - Results
+parameters:
+  -
+    in: query
+    name: action
+    type: string
+    default: getResult
+    required: true
+  -
+    in: query
+    name: measurement
+    type: string
+    description: test case name
+    required: true
+  -
+    in: query
+    name: task_id
+    type: string
+    description: the task_id you get before
+    required: true
+responses:
+  200:
+    description: a result json dict
+    schema:
+      id: ResultModel
+      properties:
+        status:
+          type: string
+          description: the status of the certain task
+          default: success
+        result:
+          schema:
+            type: array
+            items:
+              type: object
diff --git a/api/swagger/docs/testcases.yaml b/api/swagger/docs/testcases.yaml
new file mode 100644
index 000000000..7bfe5e647
--- /dev/null
+++ b/api/swagger/docs/testcases.yaml
@@ -0,0 +1,50 @@
+TestCases Actions

+

+This API may offer many actions, including runTestCase

+

+action: runTestCase

+This api offer the interface to run a test case in yardstick

+we will return a task_id for querying

+you can use the returned task_id to get the result data

+---

+tags:

+  - Release Action

+parameters:

+  - in: body

+    name: body

+    description: this is the input json dict

+    schema:

+      id: TestCaseActionModel

+      required:

+        - action

+        - args

+      properties:

+        action:

+          type: string

+          description: this is action for testcases

+          default: runTestCase

+        args:

+          schema:

+            id: TestCaseActionArgsModel

+            required:

+              - testcase

+            properties:

+              testcase:

+                type: string

+                description: this is the test case name

+                default: tc002

+              opts:

+                schema:

+                  id: TestCaseActionArgsOptsModel

+responses:

+  200:

+    description: A result json dict

+    schema:

+      id: result

+      properties:

+        status:

+          type: string

+          default: success

+        result:

+          type: string

+          description: task_id of this task

diff --git a/api/swagger/models.py b/api/swagger/models.py
new file mode 100644
index 000000000..7c65fbbf5
--- /dev/null
+++ b/api/swagger/models.py
@@ -0,0 +1,51 @@
+##############################################################################
+# Copyright (c) 2016 Huawei Technologies Co.,Ltd and others.
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Apache License, Version 2.0
+# which accompanies this distribution, and is available at
+# http://www.apache.org/licenses/LICENSE-2.0
+##############################################################################
+from flask_restful import fields
+from flask_restful_swagger import swagger
+
+
+# for testcases/action runTestCase action
+@swagger.model
+class TestCaseActionArgsOptsTaskArgModel:
+    resource_fields = {
+    }
+
+
+@swagger.model
+class TestCaseActionArgsOptsModel:
+    resource_fields = {
+        'task-args': TestCaseActionArgsOptsTaskArgModel,
+        'keep-deploy': fields.String,
+        'suite': fields.String
+    }
+
+
+@swagger.model
+class TestCaseActionArgsModel:
+    resource_fields = {
+        'testcase': fields.String,
+        'opts': TestCaseActionArgsOptsModel
+    }
+
+
+@swagger.model
+class TestCaseActionModel:
+    resource_fields = {
+        'action': fields.String,
+        'args': TestCaseActionArgsModel
+    }
+
+
+# for results
+@swagger.model
+class ResultModel:
+    resource_fields = {
+        'status': fields.String,
+        'result': fields.List
+    }
diff --git a/api/views.py b/api/views.py
index f899251dd..928d8e9eb 100644
--- a/api/views.py
+++ b/api/views.py
@@ -7,11 +7,14 @@
 # http://www.apache.org/licenses/LICENSE-2.0
 ##############################################################################
 import logging
+import os
 
 from flask import request
 from flask_restful import Resource
+from flasgger.utils import swag_from
 
 from api.utils import common as common_utils
+from api.swagger import models
 from api.actions import test as test_action
 from api.actions import samples as samples_action
 from api.actions import result as result_action
@@ -20,7 +23,14 @@ from api.actions import env as env_action
 logger = logging.getLogger(__name__)
 
 
+TestCaseActionModel = models.TestCaseActionModel
+TestCaseActionArgsModel = models.TestCaseActionArgsModel
+TestCaseActionArgsOptsModel = models.TestCaseActionArgsOptsModel
+TestCaseActionArgsOptsTaskArgModel = models.TestCaseActionArgsOptsTaskArgModel
+
+
 class Release(Resource):
+    @swag_from(os.getcwd() + '/swagger/docs/testcases.yaml')
     def post(self):
         action = common_utils.translate_to_str(request.json.get('action', ''))
         args = common_utils.translate_to_str(request.json.get('args', {}))
@@ -44,7 +54,11 @@ class Samples(Resource):
             return common_utils.error_handler('Wrong action')
 
 
+ResultModel = models.ResultModel
+
+
 class Results(Resource):
+    @swag_from(os.getcwd() + '/swagger/docs/results.yaml')
     def get(self):
         args = common_utils.translate_to_str(request.args)
         action = args.get('action', '')
diff --git a/requirements.txt b/requirements.txt
index b47951e0a..e391c9210 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -82,3 +82,5 @@ flask-restful==0.3.5
 influxdb==3.0.0
 pyroute2==0.4.10
 docker-py==1.10.6
+flasgger==0.5.13
+flask-restful-swagger==0.19