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

@@ -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)
 }

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!({
+/// json!([
-///     "uuid": "22006503-fb01-46e6-8e0e-70336dac6c63",
+///     {
-///     "nickname": "This field is nullable",
+///         "uuid": "22006503-fb01-46e6-8e0e-70336dac6c63",
-///     "user_uuid": "522bca17-de63-4706-9d18-0971867ad1e0",
+///         "nickname": "This field is nullable",
-///     "guild_uuid": "0911e468-3e9e-47bf-8381-59b30e8b68a8"
+///         "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")]

src/api/v1/mod.rs

@@ -1,3 +1,5 @@
+//! `/api/v1` Contains version 1 of the api
+
 use actix_web::{Scope, web};
 
 mod auth;

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<GuildInfo>,
     data: web::Data<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,

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,

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<Data>,

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<Data>) -> Result<HttpResponse, Error> {
     let accounts: i64 = users

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(get)
-        .service(uuid::res)
+        .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<StartAmountQuery>,
     data: web::Data<Data>,

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<Data>,

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?