docs: add swagger (#28)

Author: j3ko

README.md

@@ -1,9 +1,15 @@
 # Motionberry
 
-A lightweight solution for motion detection and video streaming on Raspberry Pi, powered by [picamera2](https://github.com/raspberrypi/picamera2).
+A lightweight solution for motion detection and video streaming on Raspberry Pi, powered by picamera2
 
 **Tested and optimized for Raspberry Pi Zero 2W with a Camera module v3**
 
+## Quick Links
+
+- [API Documentation](https://j3ko.github.io/motionberry/)
+- [Configuration Options](https://github.com/j3ko/motionberry/blob/main/config.default.yml)
+- [Report Issues](https://github.com/j3ko/motionberry/issues)
+
 ## Features v0.1.0
 
 - Support for Dockerized or bare-metal deployments
@@ -12,7 +18,7 @@ A lightweight solution for motion detection and video streaming on Raspberry Pi,
 - Triggered snapshots (JPEG)
 - Triggered clip recording
 - Output in raw H.264 or MP4 format
-- RESTful API and webhook events
+- RESTful API and webhook events ([documentation](https://j3ko.github.io/motionberry/))
 
 <div align="center">
   <img src="https://raw.githubusercontent.com/j3ko/motionberry/main/docs/screenshot.png" alt="Screenshot" style="width:100%; height:auto;">

app/__init__.py

@@ -1,15 +1,16 @@
 import logging
 from flask.logging import default_handler
-from flask import Flask, current_app
+from flask import Flask
 from app.api import api_bp
+from app.api.routes import *
 from app.ui import ui_bp
 from app.lib.camera.file_manager import FileManager
 from app.lib.camera.video_processor import VideoProcessor
 from app.lib.camera.camera_manager import CameraManager
 from app.lib.camera.stream_manager import StreamManager
 from app.lib.camera.motion_detector import MotionDetector
 from app.lib.camera.status_manager import StatusManager
-from app.lib.notification.webhook_notifier import WebhookNotifier
+from app.lib.notification.webhook_notifier import WebhookNotifier, get_webhook_specs
 from app.lib.notification.logging_notifier import LoggingNotifier
 import yaml
 import json
@@ -37,6 +38,9 @@ def create_app(config_file=None):
     app.register_blueprint(api_bp, url_prefix="/api")
     app.register_blueprint(ui_bp)
 
+    if app.config.get("env", "prod") == "dev":
+        register_openapi_spec(app, "docs/openapi.json")
+
     app.logger.info("Application initialized successfully.")
     return app
 
@@ -131,3 +135,34 @@ def configure_logging(app, config):
 
     app.logger.setLevel(numeric_level)
     app.logger.info(f"Logging configured to {log_level} level.")
+
+def register_openapi_spec(app, file_path):
+    """Registers API routes and generates the OpenAPI spec."""
+    from apispec import APISpec
+    from apispec.ext.marshmallow import MarshmallowPlugin
+    from apispec_webframeworks.flask import FlaskPlugin
+
+    spec = APISpec(
+        title="Motionberry API",
+        version=__version__,
+        openapi_version="3.0.3",
+        plugins=[FlaskPlugin(), MarshmallowPlugin()],
+    )
+    webhook_specs = get_webhook_specs()
+
+    with app.app_context():
+        spec.path(view=status)
+        spec.path(view=enable_detection)
+        spec.path(view=disable_detection)
+        spec.path(view=list_captures)
+        spec.path(view=download_capture)
+        spec.path(view=take_snapshot)
+        spec.path(view=record)
+
+        for webhook_spec in webhook_specs:
+            for path, definition in webhook_spec.items():
+                spec._paths[path] = definition
+
+        with open(file_path, "w") as f:
+            json.dump(spec.to_dict(), f, indent=2)
+        print("OpenAPI spec written to openapi.json")

app/api/routes.py

@@ -1,20 +1,77 @@
-from flask import Blueprint, jsonify, Response, request, send_from_directory, current_app, stream_with_context
+from flask import jsonify, Response, request, send_from_directory, current_app, stream_with_context
 from app.api import api_bp
-from pathlib import Path
 import os
 import queue
+from ..version import __version__
+
 
 @api_bp.route("/status", methods=["GET"])
 def status():
+    """
+    Returns the health status of the API.
+    ---
+    get:
+      summary: Check API health status
+      description: Returns the current status of the API to indicate whether it is operational.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: API is operational.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: "ok"
+    """
     return jsonify({"status": "ok"})
 
+
 @api_bp.route('/status_stream')
 def status_stream():
+    """
+    Streams real-time status updates as server-sent events.
+    ---
+    get:
+      summary: Real-time status updates
+      description: Streams real-time system status as server-sent events.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: Stream of status events.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+    """
     status_manager = current_app.config["status_manager"]
     return Response(stream_with_context(status_manager.generate_status()), content_type="text/event-stream")
 
+
 @api_bp.route("/enable_detection", methods=["POST"])
-def start_motion_detection():
+def enable_detection():
+    """
+    Enables motion detection.
+    ---
+    post:
+      summary: Enable motion detection
+      description: Starts the motion detection process.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: Motion detection started successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+        500:
+          description: Error enabling motion detection.
+    """
     motion_detector = current_app.config["motion_detector"]
     try:
         if not motion_detector.is_running:
@@ -24,9 +81,30 @@ def start_motion_detection():
             return jsonify({"status": "Motion detection is already running."})
     except Exception as e:
         return jsonify({"error": str(e)}), 500
-        
+
+
 @api_bp.route("/disable_detection", methods=["POST"])
-def stop_motion_detection():
+def disable_detection():
+    """
+    Disables motion detection.
+    ---
+    post:
+      summary: Disable motion detection
+      description: Stops the motion detection process.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: Motion detection stopped successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+        500:
+          description: Error disabling motion detection.
+    """
     motion_detector = current_app.config["motion_detector"]
     try:
         if motion_detector.is_running:
@@ -37,17 +115,63 @@ def stop_motion_detection():
     except Exception as e:
         return jsonify({"error": str(e)}), 500
 
+
 @api_bp.route("/captures", methods=["GET"])
 def list_captures():
+    """
+    Lists all captured files.
+    ---
+    get:
+      summary: List captured files
+      description: Retrieves a list of all captured files in the output directory.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: List of captures.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  captures:
+                    type: array
+                    items:
+                      type: string
+        500:
+          description: Error listing captures.
+    """
     file_manager = current_app.config["file_manager"]
     try:
         files = os.listdir(file_manager.output_dir)
         return jsonify({"captures": files})
     except Exception as e:
         return jsonify({"error": str(e)}), 500
 
+
 @api_bp.route("/captures/<path:input_path>", methods=["GET"])
 def download_capture(input_path):
+    """
+    Downloads a specific captured file.
+    ---
+    get:
+      summary: Download a captured file
+      description: Downloads a specific file from the output directory.
+      tags: ["Incoming"]
+      parameters:
+        - in: path
+          name: input_path
+          required: true
+          schema:
+            type: string
+          description: Path or filename of the capture to download.
+      responses:
+        200:
+          description: File downloaded successfully.
+          content:
+            application/octet-stream: {}
+        500:
+          description: Error downloading file.
+    """
     file_manager = current_app.config["file_manager"]
     output_dir = file_manager.output_dir.resolve()
 
@@ -62,18 +186,75 @@ def download_capture(input_path):
         return send_from_directory(output_dir, str(safe_relative_path))
     except Exception as e:
         return jsonify({"error": str(e)}), 500
-    
+
+
 @api_bp.route('/snapshot', methods=['POST'])
 def take_snapshot():
+    """
+    Takes a snapshot using the camera.
+    ---
+    post:
+      summary: Take a snapshot
+      description: Captures a still image using the camera.
+      tags: ["Incoming"]
+      responses:
+        200:
+          description: Snapshot taken successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  filename:
+                    type: string
+        500:
+          description: Error taking snapshot.
+    """
     camera_manager = current_app.config["camera_manager"]
     try:
         full_path = camera_manager.take_snapshot()
         return jsonify({"message": "Snapshot taken.", "filename": str(full_path)})
     except Exception as e:
         return jsonify({"error": str(e)}), 500
-    
+
+
 @api_bp.route('/record', methods=['POST'])
 def record():
+    """
+    Records a video for a specified duration.
+    ---
+    post:
+      summary: Record a video
+      description: Starts a video recording for a given duration.
+      tags: ["Incoming"]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                duration:
+                  type: integer
+                  description: Recording duration in seconds.
+                  example: 10
+      responses:
+        200:
+          description: Video recorded successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  filename:
+                    type: string
+        400:
+          description: Invalid input data.
+        500:
+          description: Error during recording.
+    """
     duration = request.json.get('duration', 0)
     if duration <= 0:
         return jsonify({"error": "Invalid duration"}), 400
@@ -90,4 +271,4 @@ def record():
         else:
             return jsonify({"error": "Recording failed or another recording is already in progress"}), 500
     except queue.Empty:
-        return jsonify({"error": "Recording timed out"}), 500
+        return jsonify({"error": "Recording timed out"}), 500