From 16ccf94631f36be237d2aa94a7f125bec72f1b02 Mon Sep 17 00:00:00 2001 From: Radical Date: Tue, 27 May 2025 11:52:17 +0000 Subject: [PATCH] docs: partially document codebase Should make it easier for frontend to figure out what stuff actually does, more will be added as the project goes on --- src/api/mod.rs | 4 +- src/api/v1/me/servers.rs | 26 +++++++---- src/api/v1/mod.rs | 2 + src/api/v1/servers/mod.rs | 77 ++++++++++++++++++++++++++++++++- src/api/v1/servers/uuid/icon.rs | 7 +++ src/api/v1/servers/uuid/mod.rs | 39 ++++++++++++++++- src/api/v1/stats.rs | 15 +++++++ src/api/v1/users/mod.rs | 38 ++++++++++++++-- src/api/v1/users/uuid.rs | 20 ++++++++- src/api/versions.rs | 16 ++++++- 10 files changed, 226 insertions(+), 18 deletions(-) diff --git a/src/api/mod.rs b/src/api/mod.rs index 25391eb..87c1c14 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -1,3 +1,5 @@ +//! `/api` Contains the entire API + use actix_web::Scope; use actix_web::web; @@ -5,5 +7,5 @@ mod v1; mod versions; pub fn web() -> Scope { - web::scope("/api").service(v1::web()).service(versions::res) + web::scope("/api").service(v1::web()).service(versions::get) } diff --git a/src/api/v1/me/servers.rs b/src/api/v1/me/servers.rs index 73ab139..390c31e 100644 --- a/src/api/v1/me/servers.rs +++ b/src/api/v1/me/servers.rs @@ -1,4 +1,4 @@ -//! Contains endpoint related to guild memberships +//! `/api/v1/me/servers` Contains endpoint related to guild memberships use actix_web::{get, web, HttpRequest, HttpResponse}; @@ -7,14 +7,24 @@ use crate::{api::v1::auth::check_access_token, error::Error, structs::Me, utils: /// `GET /api/v1/me/servers` Returns all guild memberships in a list /// -/// Example Response: +/// requires auth: yes +/// +/// ### Example Response /// ``` -/// json!({ -/// "uuid": "22006503-fb01-46e6-8e0e-70336dac6c63", -/// "nickname": "This field is nullable", -/// "user_uuid": "522bca17-de63-4706-9d18-0971867ad1e0", -/// "guild_uuid": "0911e468-3e9e-47bf-8381-59b30e8b68a8" -/// }); +/// json!([ +/// { +/// "uuid": "22006503-fb01-46e6-8e0e-70336dac6c63", +/// "nickname": "This field is nullable", +/// "user_uuid": "522bca17-de63-4706-9d18-0971867ad1e0", +/// "guild_uuid": "0911e468-3e9e-47bf-8381-59b30e8b68a8" +/// }, +/// { +/// "uuid": "bf95361e-3b64-4704-969c-3c5a80d10514", +/// "nickname": null, +/// "user_uuid": "522bca17-de63-4706-9d18-0971867ad1e0", +/// "guild_uuid": "69ec2ce5-3d8b-4451-b644-c2d969905458" +/// } +/// ]); /// ``` /// NOTE: UUIDs in this response are made using `uuidgen`, UUIDs made by the actual backend will be UUIDv7 and have extractable timestamps #[get("/servers")] diff --git a/src/api/v1/mod.rs b/src/api/v1/mod.rs index f711fe5..f30ad58 100644 --- a/src/api/v1/mod.rs +++ b/src/api/v1/mod.rs @@ -1,3 +1,5 @@ +//! `/api/v1` Contains version 1 of the api + use actix_web::{Scope, web}; mod auth; diff --git a/src/api/v1/servers/mod.rs b/src/api/v1/servers/mod.rs index 987d439..e864d0a 100644 --- a/src/api/v1/servers/mod.rs +++ b/src/api/v1/servers/mod.rs @@ -1,3 +1,5 @@ +//! `/api/v1/servers` Guild related endpoints + use actix_web::{HttpRequest, HttpResponse, Scope, get, post, web}; use serde::Deserialize; @@ -18,13 +20,37 @@ struct GuildInfo { pub fn web() -> Scope { web::scope("/servers") - .service(create) + .service(post) .service(get) .service(uuid::web()) } +/// `POST /api/v1/servers` Creates a new guild +/// +/// requires auth: yes +/// +/// ### Request Example +/// ``` +/// json!({ +/// "name": "My new server!" +/// }); +/// ``` +/// +/// ### Response Example +/// ``` +/// json!({ +/// "uuid": "383d2afa-082f-4dd3-9050-ca6ed91487b6", +/// "name": "My new server!", +/// "description": null, +/// "icon": null, +/// "owner_uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "roles": [], +/// "member_count": 1 +/// }); +/// ``` +/// NOTE: UUIDs in this response are made using `uuidgen`, UUIDs made by the actual backend will be UUIDv7 and have extractable timestamps #[post("")] -pub async fn create( +pub async fn post( req: HttpRequest, guild_info: web::Json, data: web::Data, @@ -47,6 +73,53 @@ pub async fn create( Ok(HttpResponse::Ok().json(guild)) } +/// `GET /api/v1/servers` Fetches all guilds +/// +/// requires auth: yes +/// +/// requires admin: yes +/// +/// ### Response Example +/// ``` +/// json!([ +/// { +/// "uuid": "383d2afa-082f-4dd3-9050-ca6ed91487b6", +/// "name": "My new server!", +/// "description": null, +/// "icon": null, +/// "owner_uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "roles": [], +/// "member_count": 1 +/// }, +/// { +/// "uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "My first server!", +/// "description": "This is a cool and nullable description!", +/// "icon": "https://nullable-url/path/to/icon.png", +/// "owner_uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "roles": [ +/// { +/// "uuid": "be0e4da4-cf73-4f45-98f8-bb1c73d1ab8b", +/// "guild_uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "Cool people", +/// "color": 15650773, +/// "is_above": c7432f1c-f4ad-4ad3-8216-51388b6abb5b, +/// "permissions": 0 +/// } +/// { +/// "uuid": "c7432f1c-f4ad-4ad3-8216-51388b6abb5b", +/// "guild_uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "Equally cool people", +/// "color": 16777215, +/// "is_above": null, +/// "permissions": 0 +/// } +/// ], +/// "member_count": 20 +/// } +/// ]); +/// ``` +/// NOTE: UUIDs in this response are made using `uuidgen`, UUIDs made by the actual backend will be UUIDv7 and have extractable timestamps #[get("")] pub async fn get( req: HttpRequest, diff --git a/src/api/v1/servers/uuid/icon.rs b/src/api/v1/servers/uuid/icon.rs index 2155f55..af9ab46 100644 --- a/src/api/v1/servers/uuid/icon.rs +++ b/src/api/v1/servers/uuid/icon.rs @@ -1,3 +1,5 @@ +//! `/api/v1/servers/{uuid}/icon` icon related endpoints, will probably be replaced by a multipart post to above endpoint + use actix_web::{HttpRequest, HttpResponse, put, web}; use futures_util::StreamExt as _; use uuid::Uuid; @@ -10,6 +12,11 @@ use crate::{ utils::get_auth_header, }; +/// `PUT /api/v1/servers/{uuid}/icon` Icon upload +/// +/// requires auth: no +/// +/// put request expects a file and nothing else #[put("{uuid}/icon")] pub async fn upload( req: HttpRequest, diff --git a/src/api/v1/servers/uuid/mod.rs b/src/api/v1/servers/uuid/mod.rs index 887fd06..80b3068 100644 --- a/src/api/v1/servers/uuid/mod.rs +++ b/src/api/v1/servers/uuid/mod.rs @@ -1,3 +1,5 @@ +//! `/api/v1/servers/{uuid}` Specific server endpoints + use actix_web::{HttpRequest, HttpResponse, Scope, get, web}; use uuid::Uuid; @@ -17,7 +19,7 @@ use crate::{ pub fn web() -> Scope { web::scope("") // Servers - .service(res) + .service(get) // Channels .service(channels::get) .service(channels::create) @@ -36,8 +38,41 @@ pub fn web() -> Scope { .service(icon::upload) } +/// `GET /api/v1/servers/{uuid}` DESCRIPTION +/// +/// requires auth: yes +/// +/// ### Response Example +/// ``` +/// json!({ +/// "uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "My first server!", +/// "description": "This is a cool and nullable description!", +/// "icon": "https://nullable-url/path/to/icon.png", +/// "owner_uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "roles": [ +/// { +/// "uuid": "be0e4da4-cf73-4f45-98f8-bb1c73d1ab8b", +/// "guild_uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "Cool people", +/// "color": 15650773, +/// "is_above": c7432f1c-f4ad-4ad3-8216-51388b6abb5b, +/// "permissions": 0 +/// } +/// { +/// "uuid": "c7432f1c-f4ad-4ad3-8216-51388b6abb5b", +/// "guild_uuid": "5ba61ec7-5f97-43e1-89a5-d4693c155612", +/// "name": "Equally cool people", +/// "color": 16777215, +/// "is_above": null, +/// "permissions": 0 +/// } +/// ], +/// "member_count": 20 +/// }); +/// ``` #[get("/{uuid}")] -pub async fn res( +pub async fn get( req: HttpRequest, path: web::Path<(Uuid,)>, data: web::Data, diff --git a/src/api/v1/stats.rs b/src/api/v1/stats.rs index 0b9567e..4e8aa32 100644 --- a/src/api/v1/stats.rs +++ b/src/api/v1/stats.rs @@ -1,3 +1,5 @@ +//! `/api/v1/stats` Returns stats about the server + use std::time::SystemTime; use actix_web::{HttpResponse, get, web}; @@ -19,6 +21,19 @@ struct Response { build_number: String, } +/// `GET /api/v1/` Returns stats about the server +/// +/// requires auth: no +/// +/// ### Response Example +/// ``` +/// json!({ +/// "accounts": 3, +/// "uptime": 50000, +/// "version": "0.1.0", +/// "build_number": "39d01bb" +/// }); +/// ``` #[get("/stats")] pub async fn res(data: web::Data) -> Result { let accounts: i64 = users diff --git a/src/api/v1/users/mod.rs b/src/api/v1/users/mod.rs index a81491c..0b80fd1 100644 --- a/src/api/v1/users/mod.rs +++ b/src/api/v1/users/mod.rs @@ -1,3 +1,5 @@ +//! `/api/v1/users` Contains endpoints related to all users + use actix_web::{HttpRequest, HttpResponse, Scope, get, web}; use crate::{ @@ -12,12 +14,42 @@ mod uuid; pub fn web() -> Scope { web::scope("/users") - .service(res) - .service(uuid::res) + .service(get) + .service(uuid::get) } +/// `GET /api/v1/users` Returns all users on this instance +/// +/// requires auth: yes +/// +/// requires admin: yes +/// +/// ### Response Example +/// ``` +/// json!([ +/// { +/// "uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "username": "user1", +/// "display_name": "Nullable Name", +/// "avatar": "https://nullable-url.com/path/to/image.png" +/// }, +/// { +/// "uuid": "d48a3317-7b4d-443f-a250-ea9ab2bb8661", +/// "username": "user2", +/// "display_name": "John User 2", +/// "avatar": "https://also-supports-jpg.com/path/to/image.jpg" +/// }, +/// { +/// "uuid": "12c4b3f8-a25b-4b9b-8136-b275c855ed4a", +/// "username": "user3", +/// "display_name": null, +/// "avatar": null +/// } +/// ]); +/// ``` +/// NOTE: UUIDs in this response are made using `uuidgen`, UUIDs made by the actual backend will be UUIDv7 and have extractable timestamps #[get("")] -pub async fn res( +pub async fn get( req: HttpRequest, request_query: web::Query, data: web::Data, diff --git a/src/api/v1/users/uuid.rs b/src/api/v1/users/uuid.rs index 6d9f904..27e3326 100644 --- a/src/api/v1/users/uuid.rs +++ b/src/api/v1/users/uuid.rs @@ -1,3 +1,5 @@ +//! `/api/v1/users/{uuid}` Specific user endpoints + use actix_web::{HttpRequest, HttpResponse, get, web}; use uuid::Uuid; @@ -5,8 +7,24 @@ use crate::{ Data, api::v1::auth::check_access_token, error::Error, structs::User, utils::get_auth_header, }; +/// `GET /api/v1/users/{uuid}` Returns user with the given UUID +/// +/// requires auth: yes +/// +/// requires relation: yes +/// +/// ### Response Example +/// ``` +/// json!({ +/// "uuid": "155d2291-fb23-46bd-a656-ae7c5d8218e6", +/// "username": "user1", +/// "display_name": "Nullable Name", +/// "avatar": "https://nullable-url.com/path/to/image.png" +/// }); +/// ``` +/// NOTE: UUIDs in this response are made using `uuidgen`, UUIDs made by the actual backend will be UUIDv7 and have extractable timestamps #[get("/{uuid}")] -pub async fn res( +pub async fn get( req: HttpRequest, path: web::Path<(Uuid,)>, data: web::Data, diff --git a/src/api/versions.rs b/src/api/versions.rs index e5695be..809d6ed 100644 --- a/src/api/versions.rs +++ b/src/api/versions.rs @@ -1,3 +1,4 @@ +//! `/api/v1/versions` Returns info about api versions use actix_web::{HttpResponse, Responder, get}; use serde::Serialize; @@ -10,8 +11,21 @@ struct Response { #[derive(Serialize)] struct UnstableFeatures; +/// `GET /api/versions` Returns info about api versions. +/// +/// requires auth: no +/// +/// ### Response Example +/// ``` +/// json!({ +/// "unstable_features": {}, +/// "versions": [ +/// "1" +/// ] +/// }); +/// ``` #[get("/versions")] -pub async fn res() -> impl Responder { +pub async fn get() -> impl Responder { let response = Response { unstable_features: UnstableFeatures, // TODO: Find a way to dynamically update this possibly?