Created Auto Documentation for Backend using flask-selfdoc

flask-backend/api/__init__.py

@@ -3,45 +3,49 @@
 from flask_login import LoginManager 
 from flask_marshmallow import Marshmallow
 from flask_cors import CORS, cross_origin
+from flask_selfdoc import Autodoc
+
 
 db = SQLAlchemy()
 ma = Marshmallow()
 
-def create_app():
-    app = Flask(__name__)
-    cors = CORS(app)
+app = Flask(__name__)
 
-    app.config['SECRET_KEY'] = 'thisismysecretkeydonotstealit'
-    app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///db.sqlite3'
-    app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
+cors = CORS(app)
+auto = Autodoc(app)
 
-    db.init_app(app)
+app.config['SECRET_KEY'] = 'thisismysecretkeydonotstealit'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///db.sqlite3'
+app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
 
-    login_manager = LoginManager()
-    login_manager.login_view = 'auth.login'
-    login_manager.init_app(app)
+db.init_app(app)
 
-    from .models.models import User
+login_manager = LoginManager()
+login_manager.login_view = 'auth.login'
+login_manager.init_app(app)
 
+from .models.models import User
 
-    @login_manager.user_loader
-    def load_user(user_id):
-        return User.query.get(int(user_id))
+@login_manager.user_loader
+def load_user(user_id):
+    return User.query.get(int(user_id))
 
-    @login_manager.unauthorized_handler
-    def unauthorized_handler():
-        return 'You are not authorized to use this route. Please Logged In.', 401
+@login_manager.unauthorized_handler
+def unauthorized_handler():
+    return 'You are not authorized to use this route. Please Logged In.', 401
 
-    from .userAuthentication.auth import auth as auth_blueprint
-    app.register_blueprint(auth_blueprint)
+from .userAuthentication.auth import auth as auth_blueprint
+app.register_blueprint(auth_blueprint)
 
-    from .routes.user import user as user_blueprint
-    app.register_blueprint(user_blueprint)
+from .routes.user import user as user_blueprint
+app.register_blueprint(user_blueprint)
 
-    from .routes.case import case as case_blueprint
-    app.register_blueprint(case_blueprint)
+from .routes.case import case as case_blueprint
+app.register_blueprint(case_blueprint)
 
-    from .routes.extraction import extraction as extraction_blueprint
-    app.register_blueprint(extraction_blueprint)
+from .routes.extraction import extraction as extraction_blueprint
+app.register_blueprint(extraction_blueprint)
 
-    return app
+@app.route('/')
+def documentation():
+    return auto.html(groups=['auth', 'admin', 'analytics', 'cases', 'extraction', 'user'], title='OpenMF Flask Server', template='doc_template.html')

flask-backend/api/routes/analytics.py

@@ -4,12 +4,13 @@
 from flask_login import login_required, current_user
 from ..models.models import User, UserSchema
 from werkzeug.security import generate_password_hash, check_password_hash
-from .. import db
+from .. import db, auto
 from sqlalchemy import text
 
 analytics = Blueprint('analytics', __name__, url_prefix='/analytics')
 
 @analytics.route('/query', methods=['POST'])
+@auto.doc('analytics')
 def execute_query():
     try:
         req = request.get_json()

flask-backend/api/routes/case.py

@@ -3,7 +3,7 @@
 from flask import Blueprint, render_template, jsonify, request
 from flask_login import login_required, current_user
 from ..models.models import Case, CaseSchema
-from .. import db
+from .. import db, auto
 
 ROOT_DIR = os.getcwd()
 
@@ -13,18 +13,30 @@
 case = Blueprint('case', __name__, url_prefix='/case')
 
 @case.route('/count', methods=["GET"])
+@auto.doc('cases')
 def count():
+    '''
+    Get number of cases
+    '''
     return jsonify({'status':200,
                     'total_users':Case.query.count()})
 
 @case.route('/list', methods=["GET"])
+@auto.doc('cases')
 def list():
+    '''
+    Get list of all cases
+    '''
     all_cases = Case.query.order_by(Case.timestamp).all()
     result = cases_schema.dump(all_cases)
     return jsonify(result)
 
 @case.route('/delete', methods=['POST'])
+@auto.doc('cases')
 def deletecase():
+    '''
+    Delete a case
+    '''
     # check if case_name is provided
     try:
         req = request.get_json()
@@ -42,23 +54,35 @@ def deletecase():
     return 'case deleted', 202
 
 @case.route('/open/<case_name>', methods=["GET"])
+@auto.doc('cases')
 def openCase(case_name):
+    '''
+    Open a case
+    '''
     os.chdir('../../..')
     path = os.getcwd()+'/data/'+case_name
     os.chdir(ROOT_DIR)
     files = os.listdir(path)
     return files
 
 @case.route('/list-files/<case_name>/<folder_name>', methods=["GET"])
+@auto.doc('cases')
 def openFolder(case_name, folder_name):
+    '''
+    Open a case folder
+    '''
     os.chdir('../../..')
     path = os.getcwd()+'/data/'+case_name+'/'+folder_name
     os.chdir(ROOT_DIR)
     files = os.listdir(path)
     return files
 
 @case.route('/list-files/<case_name>/<folder_name>/<file_name>', methods=["GET"])
+@auto.doc('cases')
 def openFile(case_name, folder_name, file_name):
+    '''
+    Open a case file
+    '''
     os.chdir('../../..')
     File = os.getcwd()+'/data/'+case_name+'/'+folder_name+'/'+file_name
     os.chdir(ROOT_DIR)

flask-backend/api/routes/extraction.py

@@ -7,7 +7,7 @@
 import subprocess
 from flask_login import login_required, current_user
 from ..models.models import Case, CaseSchema
-from .. import db
+from .. import db, auto
 ROOT_DIR = os.getcwd()
 
 case_schema = CaseSchema()
@@ -18,7 +18,11 @@
 
 
 @extraction.route('/list_devices', methods=["GET"])
+@auto.doc('extraction')
 def list_devices():
+    '''
+    List all devices available for extraction
+    '''
     with open(os.devnull, 'wb') as devnull:
         subprocess.check_call([adb_path, 'start-server'], stdout=devnull,
                               stderr=devnull)
@@ -43,8 +47,11 @@ def list_devices():
     return json.dumps(devices)
 
 @extraction.route('/extract_data', methods=["POST"])
+@auto.doc('extraction')
 def extract():
-
+    '''
+    Extract data from a device
+    '''
     # if no data is provided at all
     try:
         req = request.get_json()

flask-backend/api/routes/user.py

@@ -4,16 +4,20 @@
 from flask_login import login_required, current_user
 from ..models.models import User, UserSchema
 from werkzeug.security import generate_password_hash, check_password_hash
-from .. import db
+from .. import db, auto
 from sqlalchemy import update
 user_schema = UserSchema()
 users_schema = UserSchema(many=True)
 
 user = Blueprint('user', __name__, url_prefix='/user')
 
 @user.route('/profile', methods=["GET"])
+@auto.doc('user')
 @login_required
 def profile():
+    '''
+    Get profile of current user
+    '''
     if(current_user.has_admin): # For user
         return jsonify({'status':200,
                         'user_id':current_user.id,
@@ -37,7 +41,11 @@ def profile():
 
 
 @user.route('/getUser/<id>', methods=["GET"])
+@auto.doc('user')
 def getUser(id):
+    '''
+    Get user by id
+    '''
     user = User.query.filter_by(id=id).first()
 
     # Check if user with that id exists
@@ -64,19 +72,30 @@ def getUser(id):
                     'users': result})
 
 @user.route('/count', methods=["GET"])
+@auto.doc('user')
 def count():
+    '''
+    Get number of users
+    '''
     return jsonify({'status':200,
                     'total_users':User.query.count()})
 
 @user.route('/list', methods=["GET"])
+@auto.doc('user')
 def list():
+    '''
+    Get list of all users
+    '''
     all_users = User.query.order_by(User.timestamp).all()
     result = users_schema.dump(all_users)
     return jsonify(result)
 
 @user.route('/create', methods=['POST'])
+@auto.doc('user')
 def create_user(): # Add only admin can create functionality, once deployed on actual data base with one master user
-
+    '''
+    Create a user
+    '''
     # if no data is sent at all
     try:
         req = request.get_json()
@@ -109,8 +128,12 @@ def create_user(): # Add only admin can create functionality, once deployed on a
 
 # Route for admin to add user 
 @user.route('/add-user', methods=['POST'])
+@auto.doc('user')
 @login_required
 def add_users():
+    '''
+    Create a user (Admin Only)
+    '''
     if(current_user.has_admin == False): 
         try:
             req = request.get_json()
@@ -139,8 +162,12 @@ def add_users():
 
 # Route for admin to view all his users
 @user.route('/all-users', methods=['GET'])
+@auto.doc('user')
 @login_required
 def all_users():
+    '''
+    View all users of an admin
+    '''
     if current_user.role == 'adimn':
         all_users = User.query.filter_by(admin=current_user.email).order_by(User.timestamp).all()
         result = users_schema.dump(all_users)
@@ -150,7 +177,11 @@ def all_users():
 # Route for admin to delete a user
 @user.route('/remove-user', methods=['POST'])
 @login_required
+@auto.doc('user')
 def remove_user():
+    '''
+    Delete user of a particular admin
+    '''
     if current_user.role == 'adimn':
         try:
             req = request.get_json()
@@ -168,8 +199,12 @@ def remove_user():
 
 # Route to udate role of an user
 @user.route('/role-update', methods=['POST'])
+@auto.doc('user')
 @login_required
 def roleupdate():
+    '''
+    Update role of a user
+    '''
     if current_user.role == 'adimn':
         try: 
             req = request.get_json()
@@ -187,8 +222,12 @@ def roleupdate():
 
 
 @user.route('/delete', methods=['POST'])
+@auto.doc('user')
 @login_required
 def deleteuser():
+    '''
+    Delete a user
+    '''
     # Check if email is provided or not
     try:
         req = request.get_json()