From 58302595f372ecc6ef366cdbc707704e22220b14 Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <rpm@fthiessen.de>
Date: Fri, 30 Oct 2020 03:06:18 +0100
Subject: [PATCH] [Doc] Added full documentation to Auth

---
 flaschengeist/modules/auth/__init__.py | 98 ++++++++++++++++++--------
 1 file changed, 70 insertions(+), 28 deletions(-)

diff --git a/flaschengeist/modules/auth/__init__.py b/flaschengeist/modules/auth/__init__.py
index d50223a..c565741 100644
--- a/flaschengeist/modules/auth/__init__.py
+++ b/flaschengeist/modules/auth/__init__.py
@@ -1,13 +1,6 @@
 """Authentication plugin, provides basic routes
 
 Allow management of authentication, login, logout, etc.
-
-  ```Routes
-  /auth         POST: login (new token)
-                 GET: get all tokens for user
-  /auth/<token>  GET: get lifetime of token
-                 PUT: set new lifetime
-              DELETE: logout / delete token```
 """
 
 from flask import Blueprint, request, jsonify
@@ -27,10 +20,10 @@ class AuthRoutePlugin(Plugin):
 
 
 @auth_bp.route("/auth", methods=["POST"])
-def _login():
-    """Login in an user and create a `flaschengeist.system.models.Session` for the user.
+def login():
+    """Login in an user and create a session
 
-    Route: ``/auth``
+    Route: ``/auth`` | Method: ``POST``
 
     POST-data: {'userid': string, 'password': string}
 
@@ -61,14 +54,28 @@ def _login():
 
 @auth_bp.route("/auth", methods=["GET"])
 @login_required()
-def _get_sessions(current_session, **kwargs):
+def get_sessions(current_session, **kwargs):
+    """Get all valid sessions of current user
+
+    Route: ``/auth`` | Method: ``GET``
+
+    Returns:
+        A JSON array of `flaschengeist.system.models.session.Session` or HTTP error
+    """
     sessions = sessionController.get_users_sessions(current_session._user)
     return jsonify(sessions)
 
 
 @auth_bp.route("/auth/<token>", methods=["DELETE"])
 @login_required()
-def _delete_session(token, current_session, **kwargs):
+def delete_session(token, current_session, **kwargs):
+    """Delete a session aka "logout"
+
+    Route: ``/auth/<token>`` | Method: ``DELETE``
+
+    Returns:
+            200 Status (empty) or HTTP error
+    """
     logger.debug("Try to delete access token {{ {} }}".format(token))
     session = sessionController.get_session(token, current_session._user)
     if not session:
@@ -78,12 +85,23 @@ def _delete_session(token, current_session, **kwargs):
         raise Forbidden
     sessionController.delete_session(session)
     sessionController.clear_expired()
-    return jsonify({"ok": "ok"})
+    return ""
 
 
 @auth_bp.route("/auth/<token>", methods=["GET"])
 @login_required()
-def _get_session(token, current_session, **kwargs):
+def get_session(token, current_session, **kwargs):
+    """Retrieve information about a session
+
+    Route: ``/auth/<token>`` | Method: ``GET``
+
+    Attributes:
+        token: Token identifying session to retrieve
+        current_session: Session sent with Authorization Header
+
+    Returns:
+        JSON encoded `flaschengeist.system.models.session.Session` or HTTP error
+    """
     logger.debug("get token {{ {} }}".format(token))
     session = sessionController.get_session(token, current_session._user)
     if not session:
@@ -93,21 +111,22 @@ def _get_session(token, current_session, **kwargs):
     return jsonify(session)
 
 
-@auth_bp.route("/auth/<token>/user", methods=["GET"])
-@login_required()
-def _get_assocd_user(token, current_session, **kwargs):
-    logger.debug("get token {{ {} }}".format(token))
-    session = sessionController.get_session(token, current_session._user)
-    if not session:
-        # Return 403 error, so that users can not bruteforce tokens
-        # Valid tokens from other users and invalid tokens now are looking the same
-        raise Forbidden
-    return jsonify(session._user)
-
-
 @auth_bp.route("/auth/<token>", methods=["PUT"])
 @login_required()
-def _set_lifetime(token, current_session, **kwargs):
+def set_lifetime(token, current_session, **kwargs):
+    """Set lifetime of a session
+
+    Route: ``/auth/<token>`` | Method: ``PUT``
+
+    POST-data: ``{value: int}``
+
+    Attributes:
+        token: Token identifying the session
+        current_session: Session sent with Authorization Header
+
+    Returns:
+        HTTP-200 (empty) or HTTP error
+    """
     session = sessionController.get_session(token, current_session._user)
     if not session:
         # Return 403 error, so that users can not bruteforce tokens
@@ -117,6 +136,29 @@ def _set_lifetime(token, current_session, **kwargs):
         lifetime = request.get_json()["value"]
         logger.debug("set lifetime {{ {} }} to access token {{ {} }}".format(lifetime, token))
         sessionController.set_lifetime(session, lifetime)
-        return jsonify({"ok": "ok"})
+        return ""
     except (KeyError, TypeError):
         raise BadRequest
+
+
+@auth_bp.route("/auth/<token>/user", methods=["GET"])
+@login_required()
+def get_assocd_user(token, current_session, **kwargs):
+    """Retrieve user owning a session
+
+    Route: ``/auth/<token>/user`` | Method: ``GET``
+
+    Attributes:
+        token: Token identifying the session
+        current_session: Session sent with Authorization Header
+
+    Returns:
+        JSON encoded `flaschengeist.system.models.user.User` or HTTP error
+    """
+    logger.debug("get token {{ {} }}".format(token))
+    session = sessionController.get_session(token, current_session._user)
+    if not session:
+        # Return 403 error, so that users can not bruteforce tokens
+        # Valid tokens from other users and invalid tokens now are looking the same
+        raise Forbidden
+    return jsonify(session._user)