feat: implement OpenAPI spec for bots and root

src/routes/bots/create.rs

@@ -2,23 +2,29 @@ use crate::util::{regex::RE_USERNAME, variables::MAX_BOT_COUNT};
 
 use nanoid::nanoid;
 use revolt_quark::{
-    models::{Bot, User, user::BotInformation},
+    models::{user::BotInformation, Bot, User},
     Db, Error, Result,
 };
 
 use rocket::serde::json::Json;
-use serde::{Deserialize, Serialize};
+use serde::Deserialize;
 use ulid::Ulid;
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Bot Details
+#[derive(Validate, Deserialize, JsonSchema)]
+pub struct DataCreateBot {
+    /// Bot username
     #[validate(length(min = 2, max = 32), regex = "RE_USERNAME")]
     name: String,
 }
 
+/// # Create Bot
+///
+/// Create a new Revolt bot.
+#[openapi(tag = "Bots")]
 #[post("/create", data = "<info>")]
-pub async fn create_bot(db: &Db, user: User, info: Json<Data>) -> Result<Json<Bot>> {
+pub async fn create_bot(db: &Db, user: User, info: Json<DataCreateBot>) -> Result<Json<Bot>> {
     if user.bot.is_some() {
         return Err(Error::IsBot);
     }
@@ -40,7 +46,7 @@ pub async fn create_bot(db: &Db, user: User, info: Json<Data>) -> Result<Json<Bo
         id: id.clone(),
         username: info.name,
         bot: Some(BotInformation {
-            owner: user.id.clone()
+            owner: user.id.clone(),
         }),
         ..Default::default()
     };

src/routes/bots/delete.rs

@@ -1,6 +1,9 @@
-use rauth::util::EmptyResponse;
-use revolt_quark::{models::User, Db, Error, Ref, Result};
+use revolt_quark::{models::User, Db, EmptyResponse, Error, Ref, Result};
 
+/// # Delete Bot
+///
+/// Delete a bot by its id.
+#[openapi(tag = "Bots")]
 #[delete("/<target>")]
 pub async fn delete_bot(db: &Db, user: User, target: Ref) -> Result<EmptyResponse> {
     if user.bot.is_some() {

src/routes/bots/edit.rs

@@ -12,20 +12,31 @@ use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-#[derive(Validate, Serialize, Deserialize)]
-pub struct Data {
+/// # Bot Details
+#[derive(Validate, Serialize, Deserialize, JsonSchema)]
+pub struct DataEditBot {
+    /// Bot username
     #[validate(length(min = 2, max = 32), regex = "RE_USERNAME")]
     #[serde(skip_serializing_if = "Option::is_none")]
     name: Option<String>,
+    /// Whether the bot can be added by anyone
     public: Option<bool>,
+    /// Whether analytics should be gathered for this bot
     analytics: Option<bool>,
+    /// Interactions URL
+    #[validate(length(min = 1, max = 2048))]
     interactions_url: Option<String>,
+    /// Fields to remove from bot object
     #[validate(length(min = 1))]
     remove: Option<Vec<FieldsBot>>,
 }
 
+/// # Edit Bot
+///
+/// Edit bot details by its id.
+#[openapi(tag = "Bots")]
 #[patch("/<target>", data = "<data>")]
-pub async fn edit_bot(db: &Db, user: User, target: Ref, data: Json<Data>) -> Result<Json<Bot>> {
+pub async fn edit_bot(db: &Db, user: User, target: Ref, data: Json<DataEditBot>) -> Result<Json<Bot>> {
     if user.bot.is_some() {
         return Err(Error::IsBot);
     }
@@ -56,7 +67,7 @@ pub async fn edit_bot(db: &Db, user: User, target: Ref, data: Json<Data>) -> Res
         return Ok(Json(bot));
     }
 
-    let Data {
+    let DataEditBot {
         public,
         analytics,
         interactions_url,

src/routes/bots/fetch.rs

@@ -4,6 +4,10 @@ use revolt_quark::{
 };
 use rocket::serde::json::Json;
 
+/// # Fetch Bot
+///
+/// Fetch details of a bot you own by its id.
+#[openapi(tag = "Bots")]
 #[get("/<target>")]
 pub async fn fetch_bot(db: &Db, user: User, target: Ref) -> Result<Json<Bot>> {
     if user.bot.is_some() {

src/routes/bots/fetch_owned.rs

@@ -4,6 +4,10 @@ use revolt_quark::{
 };
 use rocket::serde::json::Json;
 
+/// # Fetch Owned Bots
+///
+/// Fetch all of the bots that you have control over.
+#[openapi(tag = "Bots")]
 #[get("/@me")]
 pub async fn fetch_owned_bots(db: &Db, user: User) -> Result<Json<Vec<Bot>>> {
     if user.bot.is_some() {

src/routes/bots/fetch_public.rs

@@ -3,17 +3,26 @@ use revolt_quark::{models::File, Db, Error, Ref, Result};
 use rocket::serde::json::Json;
 use serde::{Deserialize, Serialize};
 
-#[derive(Serialize, Deserialize)]
+/// # Public Bot
+#[derive(Serialize, Deserialize, JsonSchema)]
 pub struct PublicBot {
+    /// Bot Id
     #[serde(rename = "_id")]
     id: String,
+    /// Bot Username
     username: String,
+    /// Profile Avatar
     #[serde(skip_serializing_if = "Option::is_none")]
     avatar: Option<File>,
+    /// Profile Description
     #[serde(skip_serializing_if = "Option::is_none")]
     description: Option<String>,
 }
 
+/// # Fetch Public Bot
+///
+/// Fetch details of a public (or owned) bot by its id.
+#[openapi(tag = "Bots")]
 #[get("/<target>/invite")]
 pub async fn fetch_public_bot(db: &Db, target: Ref) -> Result<Json<PublicBot>> {
     let bot = target.as_bot(db).await?;

src/routes/bots/invite.rs

@@ -6,19 +6,32 @@ use revolt_quark::{
 use rocket::serde::json::Json;
 use serde::Deserialize;
 
-#[derive(Deserialize)]
+/// # Invite Destination
+#[derive(Deserialize, JsonSchema)]
 #[serde(untagged)]
-pub enum Destination {
-    Server { server: String },
-    Group { group: String },
+pub enum InviteBotDestination {
+    /// Invite to a server
+    Server {
+        /// Server Id
+        server: String,
+    },
+    /// Invite to a group
+    Group {
+        /// Group Id
+        group: String,
+    },
 }
 
+/// # Invite Bot
+///
+/// Invite a bot to a server or group by its id.`
+#[openapi(tag = "Bots")]
 #[post("/<target>/invite", data = "<dest>")]
 pub async fn invite_bot(
     db: &Db,
     user: User,
     target: Ref,
-    dest: Json<Destination>,
+    dest: Json<InviteBotDestination>,
 ) -> Result<EmptyResponse> {
     if user.bot.is_some() {
         return Err(Error::IsBot);
@@ -30,7 +43,7 @@ pub async fn invite_bot(
     }
 
     match dest.into_inner() {
-        Destination::Server { server } => {
+        InviteBotDestination::Server { server } => {
             let server = db.fetch_server(&server).await?;
 
             perms(&user)
@@ -48,7 +61,7 @@ pub async fn invite_bot(
 
             db.insert_member(&member).await.map(|_| EmptyResponse)
         }
-        Destination::Group { group } => {
+        InviteBotDestination::Group { group } => {
             let channel = db.fetch_channel(&group).await?;
 
             perms(&user)

src/routes/bots/mod.rs

@@ -1,4 +1,5 @@
 use rocket::Route;
+use rocket_okapi::okapi::openapi3::OpenApi;
 
 mod create;
 mod delete;
@@ -8,8 +9,8 @@ mod fetch_owned;
 mod fetch_public;
 mod invite;
 
-pub fn routes() -> Vec<Route> {
-    routes![
+pub fn routes() -> (Vec<Route>, OpenApi) {
+    openapi_get_routes_spec![
         create::create_bot,
         invite::invite_bot,
         fetch_public::fetch_public_bot,