Add swagger support for Rest API

JIRA: YARDSTICK-439

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

diff --git a/api/server.py b/api/server.py
index 3f104c6..64a2b4f 100644 (file)
--- 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 (file)
index 0000000..e69de29

diff --git a/api/swagger/docs/results.yaml b/api/swagger/docs/results.yaml
new file mode 100644 (file)
index 0000000..7bdab3e
--- /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 (file)
index 0000000..7bfe5e6
--- /dev/null
+++ b/api/swagger/docs/testcases.yaml
@@ -0,0 +1,50 @@
+TestCases Actions\r
+\r
+This API may offer many actions, including runTestCase\r
+\r
+action: runTestCase\r
+This api offer the interface to run a test case in yardstick\r
+we will return a task_id for querying\r
+you can use the returned task_id to get the result data\r
+---\r
+tags:\r
+  - Release Action\r
+parameters:\r
+  - in: body\r
+    name: body\r
+    description: this is the input json dict\r
+    schema:\r
+      id: TestCaseActionModel\r
+      required:\r
+        - action\r
+        - args\r
+      properties:\r
+        action:\r
+          type: string\r
+          description: this is action for testcases\r
+          default: runTestCase\r
+        args:\r
+          schema:\r
+            id: TestCaseActionArgsModel\r
+            required:\r
+              - testcase\r
+            properties:\r
+              testcase:\r
+                type: string\r
+                description: this is the test case name\r
+                default: tc002\r
+              opts:\r
+                schema:\r
+                  id: TestCaseActionArgsOptsModel\r
+responses:\r
+  200:\r
+    description: A result json dict\r
+    schema:\r
+      id: result\r
+      properties:\r
+        status:\r
+          type: string\r
+          default: success\r
+        result:\r
+          type: string\r
+          description: task_id of this task\r

diff --git a/api/swagger/models.py b/api/swagger/models.py
new file mode 100644 (file)
index 0000000..7c65fbb
--- /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 f899251..928d8e9 100644 (file)
--- 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 b47951e..e391c92 100644 (file)
--- 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