chore(doc): implement remainder of documentation

src/routes/servers/ban_create.rs

@@ -7,19 +7,25 @@ use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Ban Information
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataBanCreate {
+    /// Ban reason
     #[validate(length(min = 1, max = 1024))]
     reason: Option<String>,
 }
 
+/// # Ban User
+///
+/// Ban a user by their id.
+#[openapi(tag = "Server Members")]
 #[put("/<server>/bans/<target>", data = "<data>")]
 pub async fn req(
     db: &Db,
     user: User,
     server: Ref,
     target: Ref,
-    data: Json<Data>,
+    data: Json<DataBanCreate>,
 ) -> Result<Json<ServerBan>> {
     let data = data.into_inner();
     data.validate()

src/routes/servers/ban_list.rs

@@ -4,20 +4,33 @@ use revolt_quark::{perms, Db, Permission, Ref, Result};
 use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 
-#[derive(Serialize, Deserialize)]
+/// # Banned User
+///
+/// Just enoguh user information to list bans.
+#[derive(Serialize, Deserialize, JsonSchema)]
 struct BannedUser {
+    /// Id of the banned user
     #[serde(rename = "_id")]
     pub id: String,
+    /// Username of the banned user
     pub username: String,
+    /// Avatar of the banned user
     pub avatar: Option<File>,
 }
 
-#[derive(Serialize, Deserialize)]
+/// # Ban List Result
+#[derive(Serialize, Deserialize, JsonSchema)]
 pub struct BanListResult {
+    /// Users objects
     users: Vec<BannedUser>,
+    /// Ban objects
     bans: Vec<ServerBan>,
 }
 
+/// # Fetch Bans
+///
+/// Fetch all bans on a server.
+#[openapi(tag = "Server Members")]
 #[get("/<target>/bans")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<Json<BanListResult>> {
     let server = target.as_server(db).await?;

src/routes/servers/ban_remove.rs

@@ -1,5 +1,9 @@
 use revolt_quark::{models::User, perms, Db, EmptyResponse, Permission, Ref, Result};
 
+/// # Unban user
+///
+/// Remove a user's ban.
+#[openapi(tag = "Server Members")]
 #[delete("/<server>/bans/<target>")]
 pub async fn req(db: &Db, user: User, server: Ref, target: Ref) -> Result<EmptyResponse> {
     let server = server.as_server(db).await?;

src/routes/servers/channel_create.rs

@@ -10,9 +10,12 @@ use serde::{Deserialize, Serialize};
 use ulid::Ulid;
 use validator::Validate;
 
-#[derive(Serialize, Deserialize)]
+/// # Channel Type
+#[derive(Serialize, Deserialize, JsonSchema)]
 enum ChannelType {
+    /// Text Channel
     Text,
+    /// Voice Channel
     Voice,
 }
 
@@ -22,20 +25,34 @@ impl Default for ChannelType {
     }
 }
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Channel Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataCreateChannel {
+    /// Channel type
     #[serde(rename = "type", default = "ChannelType::default")]
     channel_type: ChannelType,
+    /// Channel name
     #[validate(length(min = 1, max = 32))]
     name: String,
+    /// Channel description
     #[validate(length(min = 0, max = 1024))]
     description: Option<String>,
+    /// Whether this channel is age restricted
     #[serde(skip_serializing_if = "Option::is_none")]
     nsfw: Option<bool>,
 }
 
+/// # Create Channel
+///
+/// Create a new Text or Voice channel.
+#[openapi(tag = "Server Information")]
 #[post("/<target>/channels", data = "<info>")]
-pub async fn req(db: &Db, user: User, target: Ref, info: Json<Data>) -> Result<Json<Channel>> {
+pub async fn req(
+    db: &Db,
+    user: User,
+    target: Ref,
+    info: Json<DataCreateChannel>,
+) -> Result<Json<Channel>> {
     let info = info.into_inner();
     info.validate()
         .map_err(|error| Error::FailedValidation { error })?;
@@ -50,7 +67,7 @@ pub async fn req(db: &Db, user: User, target: Ref, info: Json<Data>) -> Result<J
     let mut channels = server.channels.clone();
     channels.push(id.clone());
 
-    let Data {
+    let DataCreateChannel {
         name,
         description,
         nsfw,

src/routes/servers/invites_fetch.rs

@@ -4,16 +4,11 @@ use revolt_quark::{
 };
 
 use rocket::serde::json::Json;
-use serde::{Deserialize, Serialize};
-
-#[derive(Serialize, Deserialize, Debug, Clone)]
-pub struct ServerInvite {
-    #[serde(rename = "_id")]
-    code: String,
-    creator: String,
-    channel: String,
-}
 
+/// # Fetch Invites
+///
+/// Fetch all server invites.
+#[openapi(tag = "Server Members")]
 #[get("/<target>/invites")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<Json<Vec<Invite>>> {
     let server = target.as_server(db).await?;

src/routes/servers/member_edit.rs

@@ -10,23 +10,32 @@ use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Member Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataMemberEdit {
+    /// Member nickname
     #[validate(length(min = 1, max = 32))]
     nickname: Option<String>,
+    /// Attachment Id to set for avatar
     avatar: Option<String>,
+    /// Array of role ids
     roles: Option<Vec<String>>,
+    /// Fields to remove from channel object
     #[validate(length(min = 1))]
     remove: Option<Vec<FieldsMember>>,
 }
 
+/// # Edit Member
+///
+/// Edit a member by their id.
+#[openapi(tag = "Server Members")]
 #[patch("/<server>/members/<target>", data = "<data>")]
 pub async fn req(
     db: &Db,
     user: User,
     server: Ref,
     target: Ref,
-    data: Json<Data>,
+    data: Json<DataMemberEdit>,
 ) -> Result<Json<Member>> {
     let data = data.into_inner();
     data.validate()
@@ -37,7 +46,7 @@ pub async fn req(
 
     let mut member = target.as_member(db, &server.id).await?;
 
-    let Data {
+    let DataMemberEdit {
         nickname,
         avatar,
         roles,

src/routes/servers/member_fetch.rs

@@ -4,6 +4,10 @@ use revolt_quark::{
 };
 use rocket::serde::json::Json;
 
+/// # Fetch Member
+///
+/// Retrieve a member.
+#[openapi(tag = "Server Members")]
 #[get("/<target>/members/<member>")]
 pub async fn req(db: &Db, user: User, target: Ref, member: Ref) -> Result<Json<Member>> {
     let server = target.as_server(db).await?;

src/routes/servers/member_fetch_all.rs

@@ -2,12 +2,16 @@ use revolt_quark::{models::User, perms, presence::presence_filter_online, Db, Re
 
 use rocket::serde::json::Value;
 
+/// # Fetch Members
+///
+/// Fetch all server members.
+#[openapi(tag = "Server Members")]
 #[get("/<target>/members")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<Value> {
     let server = target.as_server(db).await?;
     perms(&user).server(&server).calc(db).await?;
 
-    let members = db.fetch_all_members(&server.id).await?;
+    let mut members = db.fetch_all_members(&server.id).await?;
 
     let mut user_ids = vec![];
     for member in &members {
@@ -15,7 +19,7 @@ pub async fn req(db: &Db, user: User, target: Ref) -> Result<Value> {
     }
 
     let online_ids = presence_filter_online(&user_ids).await;
-    let users = db
+    let mut users = db
         .fetch_users(&user_ids)
         .await?
         .into_iter()
@@ -25,6 +29,10 @@ pub async fn req(db: &Db, user: User, target: Ref) -> Result<Value> {
         })
         .collect::<Vec<User>>();
 
+    // Ensure the lists match up exactly.
+    members.sort_by(|a, b| a.id.user.cmp(&b.id.user));
+    users.sort_by(|a, b| a.id.cmp(&b.id));
+
     Ok(json!({
         "members": members,
         "users": users

src/routes/servers/member_remove.rs

@@ -1,5 +1,9 @@
 use revolt_quark::{models::User, perms, Db, EmptyResponse, Error, Permission, Ref, Result};
 
+/// # Kick Member
+///
+/// Removes a member from the server.
+#[openapi(tag = "Server Members")]
 #[delete("/<target>/members/<member>")]
 pub async fn req(db: &Db, user: User, target: Ref, member: Ref) -> Result<EmptyResponse> {
     let server = target.as_server(db).await?;

src/routes/servers/mod.rs

@@ -1,4 +1,5 @@
 use rocket::Route;
+use rocket_okapi::okapi::openapi3::OpenApi;
 
 mod server_ack;
 mod server_create;
@@ -25,8 +26,8 @@ mod roles_create;
 mod roles_delete;
 mod roles_edit;
 
-pub fn routes() -> Vec<Route> {
-    routes![
+pub fn routes() -> (Vec<Route>, OpenApi) {
+    openapi_get_routes_spec![
         server_create::req,
         server_delete::req,
         server_fetch::req,

src/routes/servers/permissions_set.rs

@@ -6,18 +6,24 @@ use revolt_quark::{
     perms, Db, Error, Override, Permission, Ref, Result,
 };
 
-#[derive(Deserialize)]
-pub struct Data {
+/// # Permission Value
+#[derive(Deserialize, JsonSchema)]
+pub struct DataSetServerRolePermission {
+    /// Allow / deny values for the role in this server.
     permissions: Override,
 }
 
+/// # Set Role Permission
+///
+/// Sets permissions for the specified role in the server.
+#[openapi(tag = "Server Permissions")]
 #[put("/<target>/permissions/<role_id>", data = "<data>", rank = 2)]
 pub async fn req(
     db: &Db,
     user: User,
     target: Ref,
     role_id: String,
-    data: Json<Data>,
+    data: Json<DataSetServerRolePermission>,
 ) -> Result<Json<Server>> {
     let data = data.into_inner();
 

src/routes/servers/permissions_set_default.rs

@@ -6,13 +6,24 @@ use revolt_quark::{
     perms, Db, Permission, Ref, Result,
 };
 
-#[derive(Deserialize)]
-pub struct Data {
+/// # Permission Value
+#[derive(Deserialize, JsonSchema)]
+pub struct DataSetServerDefaultPermission {
+    /// Default member permission value
     permissions: u64,
 }
 
+/// # Set Default Permission
+///
+/// Sets permissions for the default role in this server.
+#[openapi(tag = "Server Permissions")]
 #[put("/<target>/permissions/default", data = "<data>", rank = 1)]
-pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<Json<Server>> {
+pub async fn req(
+    db: &Db,
+    user: User,
+    target: Ref,
+    data: Json<DataSetServerDefaultPermission>,
+) -> Result<Json<Server>> {
     let data = data.into_inner();
 
     let mut server = target.as_server(db).await?;

src/routes/servers/roles_create.rs

@@ -7,15 +7,24 @@ use rocket::serde::json::{Json, Value};
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Role Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataCreateRole {
+    /// Role name
     #[validate(length(min = 1, max = 32))]
     name: String,
+    /// Ranking position
+    ///
+    /// Smaller values take priority.
     rank: Option<i64>,
 }
 
+/// # Create Role
+///
+/// Creates a new server role.
+#[openapi(tag = "Server Permissions")]
 #[post("/<target>/roles", data = "<data>")]
-pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<Value> {
+pub async fn req(db: &Db, user: User, target: Ref, data: Json<DataCreateRole>) -> Result<Value> {
     let data = data.into_inner();
     data.validate()
         .map_err(|error| Error::FailedValidation { error })?;

src/routes/servers/roles_delete.rs

@@ -1,5 +1,9 @@
 use revolt_quark::{models::User, perms, Db, EmptyResponse, Error, Permission, Ref, Result};
 
+/// # Delete Role
+///
+/// Delete a server role by its id.
+#[openapi(tag = "Server Permissions")]
 #[delete("/<target>/roles/<role_id>")]
 pub async fn req(db: &Db, user: User, target: Ref, role_id: String) -> Result<EmptyResponse> {
     let mut server = target.as_server(db).await?;

src/routes/servers/roles_edit.rs

@@ -10,25 +10,37 @@ use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Role Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataEditRole {
+    /// Role name
     #[validate(length(min = 1, max = 32))]
     name: Option<String>,
+    /// Role colour
     #[validate(length(min = 1, max = 32))]
     colour: Option<String>,
+    /// Whether this role should be displayed separately
     hoist: Option<bool>,
+    /// Ranking position
+    ///
+    /// Smaller values take priority.
     rank: Option<i64>,
+    /// Fields to remove from role object
     #[validate(length(min = 1))]
     remove: Option<Vec<FieldsRole>>,
 }
 
+/// # Edit Role
+///
+/// Edit a role by its id.
+#[openapi(tag = "Server Permissions")]
 #[patch("/<target>/roles/<role_id>", data = "<data>")]
 pub async fn req(
     db: &Db,
     user: User,
     target: Ref,
     role_id: String,
-    data: Json<Data>,
+    data: Json<DataEditRole>,
 ) -> Result<Json<Role>> {
     let data = data.into_inner();
     data.validate()
@@ -44,7 +56,7 @@ pub async fn req(
     let member_rank = permissions.get_member_rank().unwrap_or(i64::MIN);
 
     if let Some(mut role) = server.roles.remove(&role_id) {
-        let Data {
+        let DataEditRole {
             name,
             colour,
             hoist,

src/routes/servers/server_ack.rs

@@ -1,5 +1,9 @@
 use revolt_quark::{models::User, perms, Db, EmptyResponse, Ref, Result};
 
+/// # Mark Server As Read
+///
+/// Mark all channels in a server as read.
+#[openapi(tag = "Server Information")]
 #[put("/<target>/ack")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<EmptyResponse> {
     let server = target.as_server(db).await?;

src/routes/servers/server_create.rs

@@ -12,18 +12,26 @@ use validator::Validate;
 
 use crate::util::variables::MAX_SERVER_COUNT;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Server Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataCreateServer {
+    /// Server name
     #[validate(length(min = 1, max = 32))]
     name: String,
+    /// Server description
     #[validate(length(min = 0, max = 1024))]
     description: Option<String>,
+    /// Whether this server is age-restricted
     #[serde(skip_serializing_if = "Option::is_none")]
     nsfw: Option<bool>,
 }
 
+/// # Create Server
+///
+/// Create a new server.
+#[openapi(tag = "Server Information")]
 #[post("/create", data = "<info>")]
-pub async fn req(db: &Db, user: User, info: Json<Data>) -> Result<Json<Server>> {
+pub async fn req(db: &Db, user: User, info: Json<DataCreateServer>) -> Result<Json<Server>> {
     let info = info.into_inner();
     info.validate()
         .map_err(|error| Error::FailedValidation { error })?;
@@ -34,7 +42,7 @@ pub async fn req(db: &Db, user: User, info: Json<Data>) -> Result<Json<Server>>
         });
     }
 
-    let Data {
+    let DataCreateServer {
         name,
         description,
         nsfw,

src/routes/servers/server_delete.rs

@@ -1,5 +1,9 @@
 use revolt_quark::{models::User, Db, EmptyResponse, Ref, Result};
 
+/// # Delete / Leave Server
+///
+/// Deletes a server if owner otherwise leaves.
+#[openapi(tag = "Server Information")]
 #[delete("/<target>")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<EmptyResponse> {
     let server = target.as_server(db).await?;

src/routes/servers/server_edit.rs

@@ -10,29 +10,50 @@ use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Server Data
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataEditServer {
+    /// Server name
     #[validate(length(min = 1, max = 32))]
     name: Option<String>,
+    /// Server description
     #[validate(length(min = 0, max = 1024))]
     description: Option<String>,
 
+    /// Attachment Id for icon
     icon: Option<String>,
+    /// Attachment Id for banner
     banner: Option<String>,
 
+    /// Category structure for server
     #[validate]
     categories: Option<Vec<Category>>,
+    /// System message configuration
     system_messages: Option<SystemMessageChannels>,
 
-    nsfw: Option<bool>,
+    // Whether this server is age-restricted
+    // nsfw: Option<bool>,
+    /// Whether analytics should be collected for this server
+    ///
+    /// Must be enabled in order to show up on [Revolt Discover](https://rvlt.gg).
     analytics: Option<bool>,
 
+    /// Fields to remove from server object
     #[validate(length(min = 1))]
     remove: Option<Vec<FieldsServer>>,
 }
 
+/// # Edit Server
+///
+/// Edit a server by its id.
+#[openapi(tag = "Server Information")]
 #[patch("/<target>", data = "<data>")]
-pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<Json<Server>> {
+pub async fn req(
+    db: &Db,
+    user: User,
+    target: Ref,
+    data: Json<DataEditServer>,
+) -> Result<Json<Server>> {
     let data = data.into_inner();
     data.validate()
         .map_err(|error| Error::FailedValidation { error })?;
@@ -48,7 +69,7 @@ pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<J
         && data.banner.is_none()
         && data.system_messages.is_none()
         && data.categories.is_none()
-        && data.nsfw.is_none()
+        // && data.nsfw.is_none()
         && data.analytics.is_none()
         && data.remove.is_none()
     {
@@ -58,7 +79,7 @@ pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<J
         || data.icon.is_some()
         || data.banner.is_some()
         || data.system_messages.is_some()
-        || data.nsfw.is_some()
+        // || data.nsfw.is_some()
         || data.analytics.is_some()
         || data.remove.is_some()
     {
@@ -73,14 +94,14 @@ pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<J
             .await?;
     }
 
-    let Data {
+    let DataEditServer {
         name,
         description,
         icon,
         banner,
         categories,
         system_messages,
-        nsfw,
+        // nsfw,
         analytics,
         remove,
     } = data;
@@ -90,7 +111,7 @@ pub async fn req(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<J
         description,
         categories,
         system_messages,
-        nsfw,
+        // nsfw,
         analytics,
         ..Default::default()
     };

src/routes/servers/server_fetch.rs

@@ -4,6 +4,10 @@ use revolt_quark::{
 };
 use rocket::serde::json::Json;
 
+/// # Fetch Server
+///
+/// Fetch a server by its id.
+#[openapi(tag = "Server Information")]
 #[get("/<target>")]
 pub async fn req(db: &Db, user: User, target: Ref) -> Result<Json<Server>> {
     let server = target.as_server(db).await?;