Refactored and documented the HTTP API

server/src/http/project.rs

@@ -1,9 +1,14 @@
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::io::fs;
-use poem_openapi::{Object, OpenApi, payload::Json};
+use poem_openapi::{Object, OpenApi, Tags, payload::Json};
 use serde::Deserialize;
 use std::sync::Arc;
 
+#[derive(Tags)]
+enum ProjectTags {
+    Project,
+}
+
 #[derive(Deserialize, Object)]
 struct PathPayload {
     path: String,
@@ -13,8 +18,11 @@ pub struct ProjectApi {
     pub ctx: Arc<AppContext>,
 }
 
-#[OpenApi]
+#[OpenApi(tag = "ProjectTags::Project")]
 impl ProjectApi {
+    /// Get the currently open project path (if any).
+    ///
+    /// Returns null when no project is open.
     #[oai(path = "/project", method = "get")]
     async fn get_current_project(&self) -> OpenApiResult<Json<Option<String>>> {
         let result = fs::get_current_project(&self.ctx.state, self.ctx.store.as_ref())
@@ -22,6 +30,9 @@ impl ProjectApi {
         Ok(Json(result))
     }
 
+    /// Open a project and set it as the current project.
+    ///
+    /// Persists the selected path for later sessions.
     #[oai(path = "/project", method = "post")]
     async fn open_project(&self, payload: Json<PathPayload>) -> OpenApiResult<Json<String>> {
         let confirmed = fs::open_project(payload.0.path, &self.ctx.state, self.ctx.store.as_ref())
@@ -30,6 +41,7 @@ impl ProjectApi {
         Ok(Json(confirmed))
     }
 
+    /// Close the current project and clear the stored selection.
     #[oai(path = "/project", method = "delete")]
     async fn close_project(&self) -> OpenApiResult<Json<bool>> {
         fs::close_project(&self.ctx.state, self.ctx.store.as_ref()).map_err(bad_request)?;