api: Add Swagger UI for API documentation

This change adds Swagger UI to the REST API endpoint in order to
experiment with the API endpoints interactively. It also serves as the
documentation for the API endpoints.

3 files changed, 34 insertions, 3 deletions

diff --git a/opendc-web/opendc-web-api/app.py b/opendc-web/opendc-web-api/app.py
index 5041457f..c05e56b5 100755
--- a/opendc-web/opendc-web-api/app.py
+++ b/opendc-web/opendc-web-api/app.py
@@ -1,11 +1,13 @@
 #!/usr/bin/env python3
+import mimetypes
 import os
 
 from dotenv import load_dotenv
-from flask import Flask, jsonify
+from flask import Flask, jsonify, redirect
 from flask_compress import Compress
 from flask_cors import CORS
 from flask_restful import Api
+from flask_swagger_ui import get_swaggerui_blueprint
 from marshmallow import ValidationError
 
 from opendc.api.portfolios import Portfolio, PortfolioScenarios
@@ -72,13 +74,33 @@ def setup_api(app):
     return api
 
 
+def setup_swagger(app):
+    """
+    Setup Swagger UI
+    """
+    SWAGGER_URL = '/docs'
+    API_URL = '../schema.yml'
+
+    swaggerui_blueprint = get_swaggerui_blueprint(
+        SWAGGER_URL,
+        API_URL,
+        config={
+            'app_name': "OpenDC API v2"
+        }
+    )
+    app.register_blueprint(swaggerui_blueprint)
+
+
 def create_app(testing=False):
-    app = Flask(__name__)
+    app = Flask(__name__, static_url_path='/')
     app.config['TESTING'] = testing
     app.config['SECRET_KEY'] = os.environ['OPENDC_FLASK_SECRET']
     app.config['RESTFUL_JSON'] = {'cls': JSONEncoder}
     app.json_encoder = JSONEncoder
 
+    # Define YAML content type
+    mimetypes.add_type('text/yaml', '.yml')
+
     # Setup Sentry if DSN is specified
     setup_sentry()
 
@@ -89,8 +111,15 @@ def create_app(testing=False):
     compress = Compress()
     compress.init_app(app)
 
-    # Setup API
     setup_api(app)
+    setup_swagger(app)
+
+    @app.route('/')
+    def index():
+        """
+        Redirect the user to the API documentation if it accesses the API root.
+        """
+        return redirect('docs/')
 
     return app
 
diff --git a/opendc-web/opendc-web-api/requirements.txt b/opendc-web/opendc-web-api/requirements.txt
index 375ed40c..bbad97d0 100644
--- a/opendc-web/opendc-web-api/requirements.txt
+++ b/opendc-web/opendc-web-api/requirements.txt
@@ -9,6 +9,7 @@ Flask==1.1.2
 Flask-Compress==1.5.0
 Flask-Cors==3.0.9
 Flask-SocketIO==4.3.1
+flask-swagger-ui==3.36.0
 Flask-Restful==0.3.8
 greenlet==0.4.17
 httplib2==0.19.0
diff --git a/opendc-web/opendc-web-api/static/schema.yml b/opendc-web/opendc-web-api/static/schema.yml
new file mode 120000
index 00000000..153ad9dc
--- /dev/null
+++ b/opendc-web/opendc-web-api/static/schema.yml
@@ -0,0 +1 @@
+../../../opendc-api-spec.yml
\ No newline at end of file