api documentation (#876)

* api documentation

* utoipa openapi docs generator

---------

Co-authored-by: Andrej Walilko <awalilko@liquidweb.com>

daemon/src/analysis.rs

@@ -77,10 +77,15 @@ impl AnalysisWriter {
     }
 }
 
+/// The system status relating to QMDL file analysis
 #[derive(Debug, Serialize, Clone)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct AnalysisStatus {
+    /// The vector array of queued files
     queued: Vec<String>,
+    /// The file currently being analyzed
     running: Option<String>,
+    /// The vector array of finished files
     finished: Vec<String>,
 }
 
@@ -215,6 +220,16 @@ pub fn run_analysis_thread(
     });
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/analysis",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = AnalysisStatus)
+    ),
+    summary = "Analysis status",
+    description = "Show analysis status for all QMDL files."
+))]
 pub async fn get_analysis_status(
     State(state): State<Arc<ServerState>>,
 ) -> Result<Json<AnalysisStatus>, (StatusCode, String)> {
@@ -231,6 +246,20 @@ fn queue_qmdl(name: &str, analysis_status: &mut RwLockWriteGuard<AnalysisStatus>
     true
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/analysis/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Unable to queue analysis file")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL file to analyze")
+    ),
+    summary = "Start analysis",
+    description = "Begin analysis of QMDL file {name}."
+))]
 pub async fn start_analysis(
     State(state): State<Arc<ServerState>>,
     Path(qmdl_name): Path<String>,

daemon/src/battery/mod.rs

@@ -18,9 +18,13 @@ pub mod wingtech;
 
 const LOW_BATTERY_LEVEL: u8 = 10;
 
+/// Device battery information
 #[derive(Clone, Copy, PartialEq, Debug, Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct BatteryState {
+    /// The current level in percentage of the device battery
     level: u8,
+    /// A boolean indicating whether the battery is currently being charged
     is_plugged_in: bool,
 }
 

daemon/src/bin/gen_api.rs

@@ -0,0 +1,12 @@
+use std::{env, fs};
+
+fn main() {
+    let content = rayhunter_daemon::ApiDocs::generate();
+    let mut filename = "openapi.json".to_string();
+    let args: Vec<String> = env::args().collect();
+    if args.len() > 1 {
+        filename = args[1].to_string();
+    }
+
+    fs::write(filename, content).unwrap();
+}

daemon/src/config.rs

@@ -7,18 +7,30 @@ use rayhunter::analysis::analyzer::AnalyzerConfig;
 use crate::error::RayhunterError;
 use crate::notifications::NotificationType;
 
+/// The structure of a valid rayhunter configuration
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[serde(default)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct Config {
+    /// Path to store QMDL files
     pub qmdl_store_path: String,
+    /// Listening port
     pub port: u16,
+    /// Debug mode
     pub debug_mode: bool,
+    /// Internal device name
     pub device: Device,
+    /// UI level
     pub ui_level: u8,
+    /// Colorblind mode
     pub colorblind_mode: bool,
+    /// Key input mode
     pub key_input_mode: u8,
+    /// ntfy.sh URL
     pub ntfy_url: Option<String>,
+    /// Vector containing the types of enabled notifications
     pub enabled_notifications: Vec<NotificationType>,
+    /// Vector containing the list of enabled analyzers
     pub analyzers: AnalyzerConfig,
     pub min_space_to_start_recording_mb: u64,
     pub min_space_to_continue_recording_mb: u64,

daemon/src/diag.rs

@@ -17,6 +17,8 @@ use tokio::sync::{RwLock, oneshot};
 use tokio_stream::wrappers::LinesStream;
 use tokio_util::task::TaskTracker;
 
+#[cfg(feature = "apidocs")]
+use rayhunter::analysis::analyzer::ReportMetadata;
 use rayhunter::analysis::analyzer::{AnalysisLineNormalizer, AnalyzerConfig, EventType};
 use rayhunter::diag::{DataType, MessagesContainer};
 use rayhunter::diag_device::DiagDevice;
@@ -444,6 +446,18 @@ pub fn run_diag_read_thread(
 }
 
 /// Start recording API for web thread
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/start-recording",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::FORBIDDEN, description = "System is in debug mode"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Recording action unsuccessful")
+    ),
+    summary = "Start recording",
+    description = "Begin a new data capture."
+))]
 pub async fn start_recording(
     State(state): State<Arc<ServerState>>,
 ) -> Result<(StatusCode, String), (StatusCode, String)> {
@@ -476,6 +490,18 @@ pub async fn start_recording(
 }
 
 /// Stop recording API for web thread
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/stop-recording",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::FORBIDDEN, description = "System is in debug mode"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Recording action unsuccessful")
+    ),
+    summary = "Stop recording",
+    description = "Stop current data capture."
+))]
 pub async fn stop_recording(
     State(state): State<Arc<ServerState>>,
 ) -> Result<(StatusCode, String), (StatusCode, String)> {
@@ -495,6 +521,22 @@ pub async fn stop_recording(
     Ok((StatusCode::ACCEPTED, "ok".to_string()))
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/delete-recording/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::FORBIDDEN, description = "System is in debug mode"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Delete action unsuccessful"),
+        (status = StatusCode::BAD_REQUEST, description = "Bad recording name or no such recording")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL file to delete")
+    ),
+    summary = "Delete recording",
+    description = "Remove data capture file named {name}."
+))]
 pub async fn delete_recording(
     State(state): State<Arc<ServerState>>,
     Path(qmdl_name): Path<String>,
@@ -534,6 +576,18 @@ pub async fn delete_recording(
     }
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/delete-all-recordings",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::FORBIDDEN, description = "System is in debug mode"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Delete action unsuccessful")
+    ),
+    summary = "Delete all recordings",
+    description = "Remove all saved data capture files."
+))]
 pub async fn delete_all_recordings(
     State(state): State<Arc<ServerState>>,
 ) -> Result<(StatusCode, String), (StatusCode, String)> {
@@ -565,6 +619,21 @@ pub async fn delete_all_recordings(
     }
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/analysis-report/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = ReportMetadata, content_type = "application/x-ndjson"),
+        (status = StatusCode::SERVICE_UNAVAILABLE, description = "No QMDL files available; start a new recording."),
+        (status = StatusCode::NOT_FOUND, description = "File {name} not found")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL file to analyze")
+    ),
+    summary = "Analysis report",
+    description = "Download processed analysis report for QMDL file {name}, as well as the types (and versions) of analyzers used."
+))]
 pub async fn get_analysis_report(
     State(state): State<Arc<ServerState>>,
     Path(qmdl_name): Path<String>,

daemon/src/display/mod.rs

@@ -12,7 +12,9 @@ pub mod tplink_onebit;
 pub mod uz801;
 pub mod wingtech;
 
+/// A list of available display states
 #[derive(Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub enum DisplayState {
     /// We're recording but no warning has been found yet.
     Recording,

daemon/src/lib.rs

@@ -0,0 +1,71 @@
+pub mod analysis;
+pub mod battery;
+pub mod config;
+pub mod diag;
+pub mod display;
+pub mod error;
+pub mod key_input;
+pub mod notifications;
+pub mod pcap;
+pub mod qmdl_store;
+pub mod server;
+pub mod stats;
+
+#[cfg(feature = "apidocs")]
+use utoipa::OpenApi;
+
+// Add anotated paths to api docs
+#[cfg(feature = "apidocs")]
+#[derive(OpenApi)]
+#[openapi(
+    info(
+        description = "OpenAPI documentation for Rayhunter daemon\n\n**Note:** API endpoints are subject to change as needs arise, though we will try to keep them as stable as possible and notify about breaking changes in the changelogs for new versions.\n\nNo endpoints require any authentication. To use the in-browser execution on this page, you may need to disable CORS temporarily for your browser.",
+        license(
+            name = "GNU General Public License v3.0",
+            url = "https://github.com/EFForg/rayhunter/blob/main/LICENSE"
+        )
+    ),
+    paths(
+        pcap::get_pcap,
+        server::get_qmdl,
+        server::get_zip,
+        stats::get_system_stats,
+        stats::get_qmdl_manifest,
+        stats::get_log,
+        diag::start_recording,
+        diag::stop_recording,
+        diag::delete_recording,
+        diag::delete_all_recordings,
+        diag::get_analysis_report,
+        analysis::get_analysis_status,
+        analysis::start_analysis,
+        server::get_config,
+        server::set_config,
+        server::test_notification,
+        server::get_time,
+        server::set_time_offset,
+        server::debug_set_display_state
+    ),
+    servers(
+        (
+            url = "http://localhost:8080",
+            description = "ADB port bridge"
+        ),
+        (
+            url = "http://192.168.1.1:8080",
+            description = "Orbic WiFi GUI"
+        ),
+        (
+            url = "http://192.168.0.1:8080",
+            description = "TPLink WiFi GUI"
+        ),
+    )
+)]
+pub struct ApiDocs;
+
+#[cfg(feature = "apidocs")]
+impl ApiDocs {
+    pub fn generate() -> String {
+        ApiDocs::openapi().to_pretty_json().unwrap()
+    }
+}

daemon/src/notifications.rs

@@ -18,7 +18,9 @@ pub enum NotificationError {
     HttpError(reqwest::StatusCode),
 }
 
+/// Enum of valid notification types
 #[derive(Hash, Eq, PartialEq, Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub enum NotificationType {
     Warning,
     LowBattery,

daemon/src/pcap.rs

@@ -1,4 +1,4 @@
-use crate::ServerState;
+use crate::server::ServerState;
 
 use anyhow::Error;
 use axum::body::Body;
@@ -18,6 +18,21 @@ use tokio_util::io::ReaderStream;
 // Streams a pcap file chunk-by-chunk to the client by reading the QMDL data
 // written so far. This is done by spawning a thread which streams chunks of
 // pcap data to a channel that's piped to the client.
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/pcap/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::OK, description = "PCAP conversion successful", content_type = "application/vnd.tcpdump.pcap"),
+        (status = StatusCode::NOT_FOUND, description = "Could not find file {name}"),
+        (status = StatusCode::SERVICE_UNAVAILABLE, description = "QMDL file is empty")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL filename to convert and download")
+    ),
+    summary = "Download a PCAP file",
+    description = "Stream a PCAP file to a client in chunks by converting the QMDL data for file {name} written so far."
+))]
 pub async fn get_pcap(
     State(state): State<Arc<ServerState>>,
     Path(mut qmdl_name): Path<String>,

daemon/src/qmdl_store.rs

@@ -45,14 +45,25 @@ pub struct Manifest {
     pub entries: Vec<ManifestEntry>,
 }
 
+/// The structure of an entry in the QMDL manifest table
 #[derive(Deserialize, Serialize, Clone, PartialEq, Debug)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct ManifestEntry {
+    /// The name of the entry
     pub name: String,
+    /// The system time when recording began
+    #[cfg_attr(feature = "apidocs", schema(value_type = String))]
     pub start_time: DateTime<Local>,
+    /// The system time when the last message was recorded to the file
+    #[cfg_attr(feature = "apidocs", schema(value_type = String))]
     pub last_message_time: Option<DateTime<Local>>,
+    /// The size of the QMDL file in bytes
     pub qmdl_size_bytes: usize,
+    /// The rayhunter daemon version which generated the file
     pub rayhunter_version: Option<String>,
+    /// The OS which created the file
     pub system_os: Option<String>,
+    /// The architecture on which the OS was running
     pub arch: Option<String>,
     #[serde(default)]
     pub stop_reason: Option<String>,

daemon/src/server.rs

@@ -21,9 +21,9 @@ use tokio_util::compat::FuturesAsyncWriteCompatExt;
 use tokio_util::io::ReaderStream;
 use tokio_util::sync::CancellationToken;
 
-use crate::DiagDeviceCtrlMessage;
 use crate::analysis::{AnalysisCtrlMessage, AnalysisStatus};
 use crate::config::Config;
+use crate::diag::DiagDeviceCtrlMessage;
 use crate::display::DisplayState;
 use crate::pcap::generate_pcap_data;
 use crate::qmdl_store::RecordingStore;
@@ -39,6 +39,21 @@ pub struct ServerState {
     pub ui_update_sender: Option<Sender<DisplayState>>,
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/qmdl/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::OK, description = "QMDL download successful", content_type = "application/octet-stream"),
+        (status = StatusCode::NOT_FOUND, description = "Could not find file {name}"),
+        (status = StatusCode::SERVICE_UNAVAILABLE, description = "QMDL file is empty, or error opening file")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL filename to convert and download")
+    ),
+    summary = "Download a QMDL file",
+    description = "Stream the QMDL file {name} to the client."
+))]
 pub async fn get_qmdl(
     State(state): State<Arc<ServerState>>,
     Path(qmdl_name): Path<String>,
@@ -106,12 +121,38 @@ pub async fn serve_static(
     }
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/config",
+    tag = "Configuration",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = Config)
+    ),
+    summary = "Get config",
+    description = "Show the running configuration for Rayhunter."
+))]
 pub async fn get_config(
     State(state): State<Arc<ServerState>>,
 ) -> Result<Json<Config>, (StatusCode, String)> {
     Ok(Json(state.config.clone()))
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/config",
+    tag = "Configuration",
+    request_body(
+        content = Option<[Config]>,
+        description = "Any or all configuration elements from the valid config schema to be altered may be passed. Invalid keys will be discarded. Invalid values or value types will return an error."
+    ),
+    responses(
+        (status = StatusCode::ACCEPTED, description = "Success"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Failed to parse or write config file"),
+        (status = 422, description = "Failed to deserialize JSON body")
+    ),
+    summary = "Set config",
+    description = "Write a new configuration for Rayhunter and trigger a restart."
+))]
 pub async fn set_config(
     State(state): State<Arc<ServerState>>,
     Json(config): Json<Config>,
@@ -138,6 +179,18 @@ pub async fn set_config(
     ))
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/test-notification",
+    tag = "Configuration",
+    responses(
+        (status = StatusCode::OK, description = "Success"),
+        (status = StatusCode::BAD_REQUEST, description = "No notification URL set"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Failed to send HTTP request. Ensure your device can reach the internet.")
+    ),
+    summary = "Test ntfy notification",
+    description = "Send a test notification to the ntfy_url in the running configuration for Rayhunter."
+))]
 pub async fn test_notification(
     State(state): State<Arc<ServerState>>,
 ) -> Result<(StatusCode, String), (StatusCode, String)> {
@@ -174,10 +227,13 @@ pub async fn test_notification(
 
 /// Response for GET /api/time
 #[derive(Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct TimeResponse {
     /// The raw system time (without clock offset)
+    #[cfg_attr(feature = "apidocs", schema(value_type = String))]
     pub system_time: DateTime<Local>,
     /// The adjusted time (system time + offset)
+    #[cfg_attr(feature = "apidocs", schema(value_type = String))]
     pub adjusted_time: DateTime<Local>,
     /// The current offset in seconds
     pub offset_seconds: i64,
@@ -185,11 +241,22 @@ pub struct TimeResponse {
 
 /// Request for POST /api/time-offset
 #[derive(Deserialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct SetTimeOffsetRequest {
     /// The offset to set, in seconds
     pub offset_seconds: i64,
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/time",
+    tag = "Configuration",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = TimeResponse)
+    ),
+    summary = "Get time",
+    description = "Get the current time and offset (in seconds) of the device."
+))]
 pub async fn get_time() -> Json<TimeResponse> {
     let system_time = Local::now();
     let adjusted_time = rayhunter::clock::get_adjusted_now();
@@ -203,11 +270,39 @@ pub async fn get_time() -> Json<TimeResponse> {
     })
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/time-offset",
+    tag = "Configuration",
+    request_body(
+        content = SetTimeOffsetRequest
+    ),
+    responses(
+        (status = StatusCode::OK, description = "Success", body = TimeResponse)
+    ),
+    summary = "Set time offset",
+    description = "Set the difference (in seconds) between the system time and the adjusted time for Rayhunter."
+))]
 pub async fn set_time_offset(Json(req): Json<SetTimeOffsetRequest>) -> StatusCode {
     rayhunter::clock::set_offset(chrono::TimeDelta::seconds(req.offset_seconds));
     StatusCode::OK
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/zip/{name}",
+    tag = "Recordings",
+    responses(
+        (status = StatusCode::OK, description = "ZIP download successful. It is possible that if the PCAP fails to convert, the same status will be returned, but the file will contain only the QMDL file.", content_type = "application/zip"),
+        (status = StatusCode::NOT_FOUND, description = "Could not find file {name}"),
+        (status = StatusCode::SERVICE_UNAVAILABLE, description = "QMDL file is empty, or error opening file")
+    ),
+    params(
+        ("name" = String, Path, description = "QMDL filename to convert and download")
+    ),
+    summary = "Download a ZIP file",
+    description = "Stream a ZIP file to the client which contains the QMDL file {name} and a PCAP generated from the same file."
+))]
 pub async fn get_zip(
     State(state): State<Arc<ServerState>>,
     Path(entry_name): Path<String>,
@@ -299,6 +394,21 @@ pub async fn get_zip(
     Ok((headers, body).into_response())
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    post,
+    path = "/api/debug/display-state",
+    tag = "Configuration",
+    request_body(
+        content = DisplayState
+    ),
+    responses(
+        (status = StatusCode::OK, description = "Display state updated successfully"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Error sending update to the display"),
+        (status = StatusCode::SERVICE_UNAVAILABLE, description = "Display system not available")
+    ),
+    summary = "Set display state",
+    description = "Change the display state (color bar or otherwise) of the device for debugging purposes."
+))]
 pub async fn debug_set_display_state(
     State(state): State<Arc<ServerState>>,
     Json(display_state): Json<DisplayState>,

daemon/src/stats.rs

@@ -14,7 +14,9 @@ use rayhunter::{Device, util::RuntimeMetadata};
 use serde::Serialize;
 use tokio::process::Command;
 
+/// Structure of device system statistics
 #[derive(Debug, Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct SystemStats {
     pub disk_stats: DiskStats,
     pub memory_stats: MemoryStats,
@@ -41,13 +43,21 @@ impl SystemStats {
     }
 }
 
+/// Device storage information
 #[derive(Debug, Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct DiskStats {
+    /// The partition to which the daemon is installed
     partition: String,
+    /// The total disk size of the partition
     total_size: String,
+    /// Total used size of the partition
     used_size: String,
+    /// Remaining free space of the partition
     available_size: String,
+    /// Disk usage displayed as percentage
     used_percent: String,
+    /// The root folder to which the partition is mounted
     mounted_on: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub available_bytes: Option<u64>,
@@ -89,10 +99,15 @@ impl DiskStats {
     }
 }
 
+/// Device memory information
 #[derive(Debug, Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct MemoryStats {
+    /// The total memory available on the device
     total: String,
+    /// The currently used memory
     used: String,
+    /// Remaining free memory
     free: String,
 }
 
@@ -145,6 +160,17 @@ fn humanize_kb(kb: usize) -> String {
     format!("{:.1}M", kb as f64 / 1024.0)
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/system-stats",
+    tag = "Statistics",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = SystemStats),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Error collecting statistics")
+    ),
+    summary = "Get system info",
+    description = "Display system/device statistics."
+))]
 pub async fn get_system_stats(
     State(state): State<Arc<ServerState>>,
 ) -> Result<Json<SystemStats>, (StatusCode, String)> {
@@ -161,12 +187,26 @@ pub async fn get_system_stats(
     }
 }
 
+/// QMDL manifest information
 #[derive(Serialize)]
+#[cfg_attr(feature = "apidocs", derive(utoipa::ToSchema))]
 pub struct ManifestStats {
+    /// A vector containing the names of the QMDL files
     pub entries: Vec<ManifestEntry>,
+    /// The currently open QMDL file
     pub current_entry: Option<ManifestEntry>,
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/qmdl-manifest",
+    tag = "Statistics",
+    responses(
+        (status = StatusCode::OK, description = "Success", body = ManifestStats)
+    ),
+    summary = "QMDL Manifest",
+    description = "List QMDL files available on the device and some of their basic statistics."
+))]
 pub async fn get_qmdl_manifest(
     State(state): State<Arc<ServerState>>,
 ) -> Result<Json<ManifestStats>, (StatusCode, String)> {
@@ -179,6 +219,17 @@ pub async fn get_qmdl_manifest(
     }))
 }
 
+#[cfg_attr(feature = "apidocs", utoipa::path(
+    get,
+    path = "/api/log",
+    tag = "Statistics",
+    responses(
+        (status = StatusCode::OK, description = "Success", content_type = "text/plain"),
+        (status = StatusCode::INTERNAL_SERVER_ERROR, description = "Could not read /data/rayhunter/rayhunter.log file")
+    ),
+    summary = "Display log",
+    description = "Download the current device log in UTF-8 plaintext."
+))]
 pub async fn get_log() -> Result<String, (StatusCode, String)> {
     tokio::fs::read_to_string("/data/rayhunter/rayhunter.log")
         .await