[EXPERIMENTAL] swagger using flasgger

app/__init__.py

@@ -1,9 +1,26 @@
 import flask
 from app.server import routes, json_response
+from app.server.swagger import swagger
+from app.new_import import NEW_IMPORT_SCHEMA
 
 
 def create_app() -> flask.Flask:
     app = flask.Flask(__name__)
-    app.response_class = json_response.JsonResponse
     app.register_blueprint(routes.routes)
+    app.config["SWAGGER"] = {
+        'openapi': '3.0.2',
+        'definitions': { # TODO: a saner way of consolidating all these
+            "import_request": NEW_IMPORT_SCHEMA,
+            "import_status" : {
+                "type": "object",
+                "properties": {
+                    "id": { "type": "string" },
+                    "status": { "type": "string" }
+                },
+                "required": ["id", "status"]
+            }
+        }
+    }
+    swagger.init_app(app)
+    app.after_request(json_response.fixup_mimetype)
     return app

app/new_import.py

@@ -7,6 +7,9 @@
 from app.db import db, model
 from app.external import sam, pubsub
 from app.auth import user_auth
+from app.server.swagger import swagger
+
+import flasgger.base
 
 NEW_IMPORT_SCHEMA = {
   "$schema": "http://json-schema.org/draft-07/schema#",
@@ -23,7 +26,6 @@
   "required": ["path", "filetype"]
 }
 
-
 schema_validator = jsonschema.Draft7Validator(NEW_IMPORT_SCHEMA)
 
 

app/server/json_response.py

@@ -1,5 +1,9 @@
-from flask import Response
+import flask
 
 
-class JsonResponse(Response):
-    default_mimetype = "application/json"
+def fixup_mimetype(resp: flask.Response):
+    if flask.request.path.startswith("/apidocs"):
+        resp.mimetype = "text/html"
+    else:
+        resp.mimetype = "application/json"
+    return resp

app/server/routes.py

@@ -10,18 +10,62 @@
 routes = flask.Blueprint('import-service', __name__, '/')
 
 
-@routes.route('/<ws_ns>/<ws_name>/imports', methods=["POST"])
+@routes.route('/<workspace_namespace>/<workspace_name>/imports', methods=["POST"])
 @httpify_excs
-def create_import(ws_ns, ws_name) -> flask.Response:
-    """Accept an import request"""
-    return new_import.handle(flask.request, ws_ns, ws_name)
+def create_import(workspace_namespace, workspace_name) -> flask.Response:
+    """Accept an import request.
+    ---
+    parameters:
+      - name: workspace_namespace
+        in: path
+        schema:
+          type: string
+        required: true
+      - name: workspace_name
+        in: path
+        schema:
+          type: string
+        required: true
+      - name: import_request
+        in: body
+        schema:
+          $ref: '#/definitions/import_request'
+    responses:
+      201:
+        description: it's all good
+    """
+    return new_import.handle(flask.request, workspace_namespace, workspace_name)
 
 
-@routes.route('/<ws_ns>/<ws_name>/imports/<import_id>', methods=["GET"])
+@routes.route('/<workspace_namespace>/<workspace_name>/imports/<import_id>', methods=["GET"])
 @httpify_excs
-def import_status(ws_ns, ws_name, import_id) -> flask.Response:
-    """Return the status of an import job"""
-    return status.handle_get_import_status(flask.request, ws_ns, ws_name, import_id)
+def import_status(workspace_namespace, workspace_name, import_id) -> flask.Response:
+    """Return the status of an import job.
+    ---
+    parameters:
+      - name: workspace_namespace
+        in: path
+        schema:
+          type: string
+        required: true
+      - name: workspace_name
+        in: path
+        schema:
+          type: string
+        required: true
+      - name: import_id
+        in: path
+        schema:
+          type: string
+    responses:
+      200:
+        description: here's the status
+        content:
+          application/json:
+            schema:
+              $ref: '#/definitions/import_status'
+    """
+    return status.handle_get_import_status(flask.request, workspace_namespace, workspace_name, import_id)
 
 
 @routes.route('/<ws_ns>/<ws_name>/imports', methods=["GET"])

app/server/swagger.py

@@ -0,0 +1,3 @@
+import flasgger
+
+swagger = flasgger.Swagger()

mypy.ini

@@ -37,3 +37,6 @@ ignore_missing_imports = True
 
 [mypy-humps]
 ignore_missing_imports = True
+
+[mypy-flasgger.*]
+ignore_missing_imports = True

requirements.txt

@@ -24,3 +24,4 @@ gcsfs==0.6.0
 memunit==0.5.0
 psutil==5.6.7
 pyhumps==1.3.1
+flasgger==0.9.4