feat: Include a swagger UI endpoint

Author: dormant-user

Cargo.toml

@@ -26,6 +26,8 @@ path = "src/main.rs"
 rustdoc-args = ["--document-private-items"]
 
 [dependencies]
+utoipa = { version = "5.5.0", features = ["actix_extras"] }
+utoipa-swagger-ui = { version = "9.0.2", features = ["actix-web"] }
 actix-web = "4.13.0"
 reqwest = { version = "0.13.3", features = ["blocking", "cookies", "json", "form"] }
 serde = { version = "1.0.228", features = ["derive"] }

src/api.rs

@@ -13,6 +13,13 @@ use uuid::Uuid;
 /// # Returns
 ///
 /// Returns the HTTPResponse with a JSON message to indicate the API is up.
+#[utoipa::path(
+    get,
+    path = "/status",
+    responses(
+        (status = 200, description = "List of users", body = serde_json::Value),
+    ),
+)]
 pub async fn status() -> impl Responder {
     HttpResponse::Ok().json(json!({ "status": "ok" }))
 }
@@ -22,6 +29,13 @@ pub async fn status() -> impl Responder {
 /// # Returns
 ///
 /// Returns the HTTPResponse with a JSON message resolved during compile time.
+#[utoipa::path(
+    get,
+    path = "/version",
+    responses(
+        (status = 200, description = "API version", body = serde_json::Value)
+    )
+)]
 pub async fn version() -> impl Responder {
     HttpResponse::Ok().json(json!({ "version": env!("CARGO_PKG_VERSION") }))
 }
@@ -51,6 +65,13 @@ pub async fn version() -> impl Responder {
 /// # Returns
 ///
 /// Returns a JSON object to indicate the status.
+#[utoipa::path(
+    get,
+    path = "/torrent",
+    responses(
+        (status = 200, description = "Torrent status map", body = HashMap<String, String>)
+    )
+)]
 pub async fn get_torrents(
     state: web::Data<settings::SharedState>,
     config: web::Data<settings::Config>,
@@ -220,6 +241,14 @@ fn resolve_payload(body: &[settings::PutItem]) -> Vec<settings::PutItem> {
 /// # Returns
 ///
 /// Returns a JSON object to indicate the status.
+#[utoipa::path(
+    put,
+    path = "/torrent",
+    request_body = Vec<settings::PutItem>,
+    responses(
+        (status = 200, description = "Queued", body = String)
+    )
+)]
 pub async fn put_torrent(
     pending: web::Data<settings::PendingMap>,
     config: web::Data<settings::Config>,
@@ -316,6 +345,17 @@ pub async fn put_torrent(
 /// # Returns
 ///
 /// Returns a JSON object to indicate the status.
+#[utoipa::path(
+    delete,
+    path = "/torrent",
+    params(
+        ("name" = String, Query, description = "Torrent name"),
+        ("delete-files" = bool, Query, description = "Delete files")
+    ),
+    responses(
+        (status = 200, description = "Deleted", body = String)
+    )
+)]
 pub async fn delete_torrent(
     config: web::Data<settings::Config>,
     query: web::Query<HashMap<String, String>>,

src/lib.rs

@@ -1,9 +1,11 @@
 #![allow(rustdoc::bare_urls)]
 #![doc = include_str!("../README.md")]
 
-use actix_web::{web, App, HttpServer};
+use actix_web::{web, App, HttpResponse, HttpServer};
 use std::{collections::HashMap, sync::Arc};
 use tokio::sync::RwLock;
+use utoipa::OpenApi;
+use utoipa_swagger_ui::SwaggerUi;
 
 mod api;
 mod logger;
@@ -12,6 +14,16 @@ mod rsync;
 mod settings;
 mod squire;
 
+#[derive(OpenApi)]
+#[openapi(paths(
+    api::status,
+    api::version,
+    api::get_torrents,
+    api::put_torrent,
+    api::delete_torrent
+))]
+struct ApiDoc;
+
 /// Contains entrypoint and initializer settings to trigger the asynchronous `HTTPServer`
 ///
 /// # Examples
@@ -44,6 +56,7 @@ pub async fn start() -> std::io::Result<()> {
         port,
         workers
     );
+    let openapi = ApiDoc::openapi();
 
     HttpServer::new(move || {
         App::new()
@@ -56,6 +69,17 @@ pub async fn start() -> std::io::Result<()> {
             .route("/torrent", web::get().to(api::get_torrents))
             .route("/torrent", web::put().to(api::put_torrent))
             .route("/torrent", web::delete().to(api::delete_torrent))
+            .route(
+                "/swagger",
+                web::get().to(|| async {
+                    HttpResponse::Found()
+                        .append_header(("Location", "/swagger-ui/"))
+                        .finish()
+                }),
+            )
+            .service(
+                SwaggerUi::new("/swagger-ui/{_:.*}").url("/api-docs/openapi.json", openapi.clone()),
+            )
     })
     .bind((host, port))?
     .workers(workers)

src/settings.rs

@@ -1,9 +1,9 @@
 use crate::squire;
-use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::num::NonZeroUsize;
 use std::sync::Arc;
 use tokio::sync::RwLock;
+use utoipa::ToSchema;
 
 /// ### SharedState
 /// Shared application state for tracking active rsync operations.
@@ -79,7 +79,7 @@ impl Config {
 
 /// ### Status
 /// Represents the current status of a torrent or transfer.
-#[derive(Clone, Debug, Serialize)]
+#[derive(Clone, Debug, serde::Serialize)]
 pub enum Status {
     Downloading(f64),
     Copying(f64),
@@ -97,7 +97,7 @@ pub struct RsyncTrack {
 
 /// ### RsyncTarget
 /// Defines a remote rsync destination.
-#[derive(Clone, Debug, Deserialize)]
+#[derive(Clone, Debug, serde::Deserialize)]
 pub struct RsyncTarget {
     pub host: String,
     pub username: String,
@@ -106,7 +106,7 @@ pub struct RsyncTarget {
 
 /// ### PutItem
 /// Represents an incoming request to add a new torrent with optional rsync target details.
-#[derive(Deserialize, Clone, Debug)]
+#[derive(ToSchema, Clone, serde::Serialize, serde::Deserialize)]
 pub struct PutItem {
     pub url: String,