TIG-1956: Add openapi support (#2)

* TIG-1956: Add openapi support

Author: zamj

README.md

@@ -37,6 +37,18 @@ $ black src tests --config setup.cfg
 See the black [documentation](https://github.com/psf/black#editor-integration) for details on how
 to configure your editor to automatically format your code.
 
+##Swagger
+
+The swagger documentation for this service can be found at the /swagger endpoint. If running
+locally, navigate to http://localhost:8080/swagger to see it.
+
+If any new endpoints are added to the service or if the service is updated in such a way that any of
+the existing endpoints' contracts change, the swagger documentation must be updated to reflect the
+new state of the service before that change can be merged to master.
+
+Documentation for how the swagger documentation is done can be found 
+[here](https://flask-restplus.readthedocs.io/en/stable/swagger.html).
+
 ## Deploy
 
 Deployment is done via helm to [kanopy](https://github.com/10gen/kanopy-docs#index). The project

requirements.txt

@@ -1,4 +1,4 @@
 black==19.3b0
 gunicorn==19.9.0
 pytest-flake8==1.0.4
-pytest==4.2.1
+pytest==5.2.0

setup.py

@@ -38,6 +38,7 @@
     ],
     install_requires=[
         'flask==1.0.4',
+        'flask-restplus==0.13.0',
     ],
     entry_points={
         'console_scripts': [

src/selectedtests/app/app.py

@@ -2,7 +2,10 @@
 Application to serve API of selected-tests service.
 """
 
-from flask import Flask, jsonify
+from flask import Flask
+from flask_restplus import Api
+
+from selectedtests.app.controllers.health_controller import add_health_endpoints
 
 DEFAULT_PORT = 8080
 
@@ -14,13 +17,15 @@ def create_app() -> Flask:
     :return: Instance of flask application.
     """
     app = Flask(__name__)
-
-    @app.route("/health")
-    def health():
-        """
-        Get information about whether service is running
-        """
-        return jsonify({"online": True})
+    api = Api(
+        app,
+        version="1.0",
+        title="Selected Tests Service",
+        description="This service is used to predict which tests need to run based on code changes",
+        doc="/swagger",
+    )
+
+    add_health_endpoints(api)
 
     return app
 

src/selectedtests/app/controllers/__init__.py

@@ -0,0 +1,29 @@
+"""
+The controller for the health endpoints.
+"""
+from flask import jsonify
+from flask_restplus import Api, Resource, fields
+
+
+def add_health_endpoints(api: Api):
+    """
+    This adds to the given app instance the health endpoints of the service
+    :param api: An instance of a Flask Restplus Api that wraps a Flask instance
+    """
+
+    ns = api.namespace("health", description="Health check endpoint")
+
+    health_model = ns.model("HealthCheckResponse", {"online": fields.Boolean})
+
+    @ns.route("")
+    class Health(Resource):
+        """
+        The class that represents the collection of endpoints that give the health of the service.
+        """
+
+        @ns.response(200, "Success", health_model)
+        def get(self):
+            """
+            Get the current status of the service
+            """
+            return jsonify({"online": True})

src/selectedtests/app/controllers/health_controller.py

@@ -1,7 +1,7 @@
 from flask import testing
 
 
-def test_health(app_client: testing.FlaskClient):
+def test_health_endpoint(app_client: testing.FlaskClient):
     """
     Test /health endpoint
     """