add: backup version converter/ backup logic 1.0

2025-04-25 13:00:41 +01:00
parent 35c8934963
commit 84494827ad
15 changed files with 2107 additions and 76 deletions
--- a/api/markdown.py
+++ b/api/markdown.py
@@ -19,6 +19,17 @@ markdown_bp = Blueprint('markdown', __name__, url_prefix='/api/markdown')
@limiter.limit(api.get_rate_limit)
@etag_response
 def get_markdowns():
+    """
+    Get all markdown documents.
+
+    This endpoint retrieves a list of all markdown documents in the system.
+
+    Returns:
+        A JSON array containing all markdown documents.
+
+    Response Codes:
+        - 200: Success
+    """
    with get_db() as session:
        mds = session.query(Markdown).all()
    return jsonify([md.to_dict() for md in mds]), 200
@@ -27,6 +38,19 @@ def get_markdowns():
@limiter.limit(api.get_rate_limit)
@etag_response
 def get_home():
+    """
+    Get the home markdown document.
+
+    This endpoint retrieves the index markdown document from the root path (path_id=1).
+    This is typically the main landing page content.
+
+    Returns:
+        A JSON object containing the home markdown document.
+
+    Response Codes:
+        - 200: Success
+        - 204: No content (home markdown not found)
+    """
    with get_db() as session:
        markdown = session.query(Markdown).filter(Markdown.path_id == 1, Markdown.title == "index").first()
        if markdown is None:
@@ -37,6 +61,20 @@ def get_home():
@limiter.limit(api.get_rate_limit)
@etag_response
 def get_markdowns_by_path(path_id):
+    """
+    Get all markdown documents in a specific path.
+
+    This endpoint retrieves a list of all markdown documents that belong to the specified path.
+
+    Request:
+        - path_id (int): The ID of the path to get markdowns from
+
+    Returns:
+        A JSON array containing all markdown documents in the specified path.
+
+    Response Codes:
+        - 200: Success
+    """
    with get_db() as session:
        markdowns = session.query(Markdown).filter(Markdown.path_id == path_id).all()
        return jsonify([md.to_dict() for md in markdowns]), 200
@@ -45,6 +83,22 @@ def get_markdowns_by_path(path_id):
@limiter.limit(api.get_rate_limit)
@etag_response
 def get_index(path_id):
+    """
+    Get the index markdown document for a specific path.
+
+    This endpoint retrieves the index markdown document from the specified path.
+    The index document typically serves as the main content or landing page for a path.
+
+    Request:
+        - path_id (int): The ID of the path to get the index markdown from
+
+    Returns:
+        A JSON object containing the index markdown document.
+
+    Response Codes:
+        - 200: Success
+        - 204: No content (index markdown not found)
+    """
    with get_db() as session:
        markdown = session.query(Markdown).filter(Markdown.path_id == path_id).filter(Markdown.title == "index").first()
        if markdown is None:
@@ -57,6 +111,24 @@ def get_index(path_id):
@limiter.limit(api.get_rate_limit)
@etag_response
 def get_markdown(markdown_id):
+    """
+    Get a specific markdown document by ID.
+
+    This endpoint retrieves a markdown document by its ID. It includes permission checks
+    based on the user's role and the markdown's permission settings.
+
+    Request:
+        - markdown_id (int): The ID of the markdown document to retrieve
+
+    Returns:
+        A JSON object containing the markdown document.
+
+    Response Codes:
+        - 200: Success
+        - 203: Permission denied (for protected markdowns when user is not an admin)
+        - 403: Permission denied (for private markdowns when user is not an admin)
+        - 404: Markdown not found
+    """
    is_admin = is_user_admin()

    with get_db() as session:
@@ -80,6 +152,27 @@ def get_markdown(markdown_id):
@require_auth(roles=['admin', 'creator'])
@limiter.limit(api.get_rate_limit)
 def create_markdown():
+    """
+    Create a new markdown document.
+
+    This endpoint creates a new markdown document with the provided data.
+    It requires authentication with either 'admin' or 'creator' role.
+
+    Request:
+        - title (str): The title of the markdown document
+        - content (str): The content of the markdown document
+        - path_id (int): The ID of the path where the markdown will be created
+        - shortcut (str, optional): A shortcut identifier for the markdown
+        - setting_id (int, optional): The ID of the markdown settings
+
+    Returns:
+        A JSON object containing the created markdown document.
+
+    Response Codes:
+        - 201: Created successfully
+        - 400: Bad request (missing required fields or duplicate shortcut)
+        - 500: Server error
+    """
    data = request.json
    title = data.get('title')
    content = data.get('content')
@@ -109,6 +202,31 @@ def create_markdown():
@require_auth(roles=['admin', 'creator'])
@limiter.limit(api.get_rate_limit)
 def update_markdown(markdown_id):
+    """
+    Update a markdown document.
+
+    This endpoint updates an existing markdown document with the provided data.
+    It requires authentication with either 'admin' or 'creator' role.
+
+    - PUT: Replaces the entire markdown document
+    - PATCH: Updates only the specified fields
+
+    Request:
+        - markdown_id (int): The ID of the markdown document to update
+        - title (str, optional for PATCH): The new title for the markdown
+        - content (str, optional for PATCH): The new content for the markdown
+        - path_id (int, optional for PATCH): The new path ID for the markdown
+        - shortcut (str, optional): A shortcut identifier for the markdown
+        - setting_id (int, optional): The ID of the markdown settings
+
+    Returns:
+        A JSON object containing the updated markdown document.
+
+    Response Codes:
+        - 200: Updated successfully
+        - 400: Bad request (duplicate shortcut)
+        - 404: Markdown not found
+    """
    with get_db() as session:
        markdown = session.query(Markdown).get(markdown_id)
        if markdown is None:
@@ -147,6 +265,22 @@ def update_markdown(markdown_id):
@require_auth(roles=['admin'])
@limiter.limit(api.get_rate_limit)
 def delete_markdown(markdown_id):
+    """
+    Delete a markdown document.
+
+    This endpoint deletes an existing markdown document.
+    It requires authentication with the 'admin' role.
+
+    Request:
+        - markdown_id (int): The ID of the markdown document to delete
+
+    Returns:
+        A JSON object containing the deleted markdown document.
+
+    Response Codes:
+        - 200: Deleted successfully
+        - 404: Markdown not found
+    """
    with get_db() as session:
        markdown = session.get(Markdown, markdown_id)
        if markdown is None:
@@ -164,6 +298,24 @@ def delete_markdown(markdown_id):
@require_auth(roles=['admin'])
@limiter.limit(api.get_rate_limit)
 def move_forward(markdown_id):
+    """
+    Move a markdown document forward in display order.
+
+    This endpoint moves a markdown document one position forward in the display order by swapping its order value
+    with the previous markdown in the same path. This affects how markdowns are displayed in the UI.
+    It requires authentication with the 'admin' role.
+
+    Request:
+        - markdown_id (int): The ID of the markdown document to move forward
+
+    Returns:
+        A JSON object containing the updated markdown document.
+
+    Response Codes:
+        - 200: Moved successfully
+        - 400: Bad request (already at the first position)
+        - 404: Markdown not found
+    """
    with get_db() as session:
        markdown = session.query(Markdown).get(markdown_id)
        if not markdown:
@@ -183,6 +335,24 @@ def move_forward(markdown_id):
@require_auth(roles=['admin'])
@limiter.limit(api.get_rate_limit)
 def move_backward(markdown_id):
+    """
+    Move a markdown document backward in display order.
+
+    This endpoint moves a markdown document one position backward in the display order by swapping its order value
+    with the next markdown in the same path. This affects how markdowns are displayed in the UI.
+    It requires authentication with the 'admin' role.
+
+    Request:
+        - markdown_id (int): The ID of the markdown document to move backward
+
+    Returns:
+        A JSON object containing the updated markdown document.
+
+    Response Codes:
+        - 200: Moved successfully
+        - 400: Bad request (already at the last position)
+        - 404: Markdown not found
+    """
    with get_db() as session:
        markdown = session.get(Markdown, markdown_id)
        if not markdown:
@@ -201,6 +371,21 @@ def move_backward(markdown_id):
@markdown_bp.route('/search/<string:keyword>', methods=['GET'])
@limiter.limit(api.get_rate_limit)
 def search_markdowns(keyword):
+    """
+    Search for markdown documents.
+
+    This endpoint searches for markdown documents that contain the specified keyword
+    in either their title or content.
+
+    Request:
+        - keyword (str): The search term to look for in markdown titles and content
+
+    Returns:
+        A JSON array containing all markdown documents that match the search criteria.
+
+    Response Codes:
+        - 200: Success
+    """
    with get_db() as session:
        res = session.query(Markdown).filter(
            or_(Markdown.title.like(keyword), Markdown.content.like(keyword))
@@ -210,6 +395,18 @@ def search_markdowns(keyword):
@markdown_bp.route('/links', methods=['GET'])
@limiter.limit(api.get_rate_limit)
 def get_links():
+    """
+    Get all markdown shortcut links.
+
+    This endpoint retrieves a list of all markdown documents that have a shortcut defined,
+    formatted as links in the format "[shortcut]: id".
+
+    Returns:
+        A JSON array containing formatted links for all markdown documents with shortcuts.
+
+    Response Codes:
+        - 200: Success
+    """
    with get_db() as session:
        mds = [md.to_dict() for md in session.query(Markdown).filter(Markdown.shortcut != "").all()]
        links = [f"[{md['shortcut']}]: {md['id']}" for md in mds]