base swagger implementation for task API

pybossa/api/__init__.py

@@ -132,15 +132,18 @@ def register_api(view, endpoint, url, pk='id', pk_type='int'):
     view_func = view.as_view(endpoint)
     csrf.exempt(view_func)
     blueprint.add_url_rule(url,
+                           endpoint=endpoint,
                            view_func=view_func,
                            defaults={pk: None},
                            methods=['GET', 'OPTIONS'])
     blueprint.add_url_rule(url,
+                           endpoint=endpoint,
                            view_func=view_func,
                            methods=['POST', 'OPTIONS'])
     blueprint.add_url_rule('%s/<%s:%s>' % (url, pk_type, pk),
-                           view_func=view_func,
-                           methods=['GET', 'PUT', 'DELETE', 'OPTIONS'])
+                            endpoint=endpoint + '_' + pk,
+                            view_func=view_func,
+                            methods=['GET', 'PUT', 'DELETE', 'OPTIONS'])
 
 register_api(ProjectAPI, 'api_project', '/project', pk='oid', pk_type='int')
 register_api(ProjectStatsAPI, 'api_projectstats', '/projectstats', pk='oid', pk_type='int')

pybossa/api/api_base.py

@@ -30,6 +30,7 @@
 from flask import request, abort, Response, current_app
 from flask_login import current_user
 from flask.views import MethodView
+from flasgger import swag_from
 from werkzeug.exceptions import NotFound, Unauthorized, Forbidden, BadRequest
 from werkzeug.exceptions import MethodNotAllowed
 from pybossa.util import jsonpify, fuzzyboolean, get_avatar_url
@@ -124,6 +125,7 @@ def options(self, **kwargs):  # pragma: no cover
 
     @jsonpify
     @ratelimit(limit=ratelimits.get('LIMIT'), per=ratelimits.get('PER'))
+    @swag_from('docs/task/task_get.yaml', endpoint='api.api_task_oid')
     def get(self, oid):
         """Get an object.
 
@@ -314,6 +316,7 @@ def _set_limit_and_offset(self):
 
     @jsonpify
     @ratelimit(limit=ratelimits.get('LIMIT'), per=ratelimits.get('PER'))
+    @swag_from('docs/task/task_post.yaml', endpoint='api.api_task')
     def post(self):
         """Post an item to the DB with the request.data JSON object.
 
@@ -383,6 +386,7 @@ def _create_instance_from_request(self, data):
 
     @jsonpify
     @ratelimit(limit=ratelimits.get('LIMIT'), per=ratelimits.get('PER'))
+    @swag_from('docs/task/task_delete.yaml', endpoint='api.api_task_oid')
     def delete(self, oid):
         """Delete a single item from the DB.
 

pybossa/api/docs/task/task_delete.yaml

@@ -0,0 +1,41 @@
+Delete a task
+---
+parameters:
+  - name: oid
+    in: path
+    type: number
+    required: true
+    description: the task id
+responses:
+  200:
+    description: deleted task info
+    schema:
+      $ref: '#definitions/Task'
+    examples:
+      {
+        "info": {
+          "company": "Bloomberg",
+          "task": "2",
+          "set_id": "2"
+        },
+        "fav_user_ids": null,
+        "user_pref": {
+        },
+        "n_answers": 1,
+        "quorum": 0,
+        "links": [
+          "<link rel='parent' title='project' href='https://qa.gigwork.net/api/project/2454'/>"
+        ],
+        "calibration": 0,
+        "expiration": null,
+        "created": "2021-04-30T21:56:30.632483",
+        "worker_filter": null,
+        "state": "completed",
+        "gold_answers": null,
+        "link": "<link rel='self' title='task' href='https://qa.gigwork.net/api/task/7225337'/>",
+        "exported": true,
+        "project_id": 2454,
+        "worker_pref": null,
+        "id": 7225337,
+        "priority_0": 0.99
+      }

pybossa/api/docs/task/task_get.yaml

@@ -0,0 +1,87 @@
+Get task information by task id
+---
+definitions:
+  Task:
+    type: object
+    properties:
+      info:
+        type: object
+        additionalProperties:
+          type: string
+      fav_user_ids:
+        type: number
+      user_pref:
+        type: object
+        additionalProperties:
+          type: string
+      n_answers:
+        type: integer
+      quorum:
+        type: integer
+      links:
+        type: array
+        items:
+          type: string
+      calibration:
+        type: integer
+      expiration:
+        type: number
+      created:
+        type: string
+      worker_filter:
+        type: string
+      state:
+        type: string
+      gold_answers:
+        type: string
+      link:
+        type: string
+      exported:
+        type: boolean
+      project_id:
+        type: integer
+      worker_pref:
+        type: number
+      id:
+        type: integer
+      priority_0:
+        type: number
+parameters:
+  - name: oid
+    in: path
+    type: number
+    required: true
+    description: the task id
+responses:
+  200:
+    description: Task info
+    schema:
+      $ref: '#definitions/Task'
+    examples:
+      {
+        "info": {
+          "company": "Bloomberg",
+          "task": "2",
+          "set_id": "2"
+        },
+        "fav_user_ids": null,
+        "user_pref": {
+        },
+        "n_answers": 1,
+        "quorum": 0,
+        "links": [
+          "<link rel='parent' title='project' href='https://qa.gigwork.net/api/project/2454'/>"
+        ],
+        "calibration": 0,
+        "expiration": null,
+        "created": "2021-04-30T21:56:30.632483",
+        "worker_filter": null,
+        "state": "completed",
+        "gold_answers": null,
+        "link": "<link rel='self' title='task' href='https://qa.gigwork.net/api/task/7225337'/>",
+        "exported": true,
+        "project_id": 2454,
+        "worker_pref": null,
+        "id": 7225337,
+        "priority_0": 0.99
+      }

pybossa/api/docs/task/task_post.yaml

@@ -0,0 +1,82 @@
+Create task via POST with json data payload
+---
+parameters:
+  - name: task
+    required: true
+    description: the task to create
+    schema:
+      type: object
+      required:
+      - project_id
+        info
+      properties:
+        project_id:
+          type: integer
+        info:
+          type: object
+          additionalProperties:
+            type: string
+        user_pref:
+          type: object
+          additionalProperties:
+            type: string
+        fav_user_ids:
+          type: array
+          items:
+            type: integer
+        n_answers:
+          type: integer
+        gold_answers:
+          type: object
+          additionalProperties:
+            type: string
+        worker_filter:
+          type: object
+          additionalProperties:
+            type: string
+        worker_pref:
+          type: object
+          additionalProperties:
+            type: string
+        expiration:
+          type: string
+    examples:
+      project_id: 1185
+      info:
+        col_1: traditional chinese task
+      user_pref:
+        languages:
+        - traditional chinese
+responses:
+  200:
+    description: created task info
+    schema:
+      $ref: '#definitions/Task'
+    examples:
+      {
+        "info": {
+          "company": "Bloomberg",
+          "task": "2",
+          "set_id": "2"
+        },
+        "fav_user_ids": null,
+        "user_pref": {
+        },
+        "n_answers": 1,
+        "quorum": 0,
+        "links": [
+          "<link rel='parent' title='project' href='https://qa.gigwork.net/api/project/2454'/>"
+        ],
+        "calibration": 0,
+        "expiration": null,
+        "created": "2021-04-30T21:56:30.632483",
+        "worker_filter": null,
+        "state": "completed",
+        "gold_answers": null,
+        "link": "<link rel='self' title='task' href='https://qa.gigwork.net/api/task/7225337'/>",
+        "exported": true,
+        "project_id": 2454,
+        "worker_pref": null,
+        "id": 7225337,
+        "priority_0": 0.99
+      }

pybossa/core.py

@@ -27,6 +27,7 @@
 from flask_json_multidict import get_json_multidict
 from flask_talisman import Talisman
 from flask_wtf.csrf import CSRFError
+from flasgger import Swagger
 from pybossa import default_settings
 from pybossa.extensions import *
 from pybossa.ratelimit import get_view_rate_limit
@@ -46,6 +47,7 @@ def create_app(run_as_server=True):
 
     setup_logging(run_as_server)
     app = Flask(__name__.split('.')[0])
+    swag  = Swagger(app)
     configure_app(app)
     global talisman
     talisman = Talisman(app, content_security_policy={
@@ -95,6 +97,7 @@ def create_app(run_as_server=True):
     anonymizer.init_app(app)
     setup_task_presenter_editor(app)
     setup_schedulers(app)
+
     return app
 
 # construct rq_dashboard config