add api documentation

1 files changed, 35 insertions, 18 deletions

diff --git a/src/auth.rs b/src/auth.rs
index 9c6f978..857ef6b 100644
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -4,6 +4,8 @@ use actix_web::{delete, post, web, HttpResponse, Scope};
 use chrono::{Duration, Utc};
 use jsonwebtoken::{encode, EncodingKey, Header};
 use serde::{Deserialize, Serialize};
+pub use crate::api::Response;
+use utoipa::ToSchema;
 
 /* Set up scope */
 pub fn auth_scope() -> Scope {
@@ -19,28 +21,23 @@ pub struct Claims {
     pub exp: usize,
 }
 
-#[derive(Serialize, Deserialize)]
-struct Response {
-    message: String,
-}
-
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
 struct EncodeResponse {
+    #[schema(example = "response")]
     message: String,
+    #[schema(example = "4f4bf0b9ef653818a56df74cffb024bd")]
     token: String,
 }
 
-#[derive(Serialize, Deserialize)]
-struct DecodeResponse {
-    message: String,
-    id: usize,
-}
-
-#[derive(Serialize, Deserialize)]
-struct DecodeBody {
-    token: String,
-}
-
+#[utoipa::path(
+    request_body = UserForm,
+    context_path = "/auth",
+    description = "Creates a new user with the specified values.",
+    responses(
+        (status = 200, description = "Create new user", body = Response),
+        (status = 400, description = "Errors found, unfulfilled request"),
+    ),
+)]
 #[post("/register")]
 pub async fn register(
     app_state: web::Data<AppState>,
@@ -57,6 +54,16 @@ pub async fn register(
     }
 }
 
+#[utoipa::path(
+    request_body = UserForm,
+    context_path = "/auth",
+    description = "Attempts to log in user. If successful, it returns an encoded token that grants access to protected routes in the api.",
+    responses(
+        (status = 200, description = "Returns encoded token", body = EncodeResponse),
+        (status = 400, description = "Errors found, unfulfilled request"),
+        (status = 401, description = "Unauthorized"),
+    ),
+)]
 #[post("/login")]
 pub async fn login(
     app_state: web::Data<AppState>,
@@ -67,7 +74,7 @@ pub async fn login(
     let result = match query {
         Ok(res) => res,
         Err(e) => {
-            return HttpResponse::BadRequest().json(Response {
+            return HttpResponse::Unauthorized().json(Response {
                 message: format!("There was an issue in the request: {}", e).to_owned(),
             })
         }
@@ -113,6 +120,16 @@ async fn encode_token(id: usize, secret: &String) -> Result<String, HttpResponse
     };
 }
 
+#[utoipa::path(
+    request_body = UserForm,
+    context_path = "/auth",
+    description = "Attempts to delete user. Both username and password are required.",
+    responses(
+        (status = 200, description = "Delete user", body = Response),
+        (status = 400, description = "Errors found, unfulfilled request"),
+        (status = 401, description = "Unauthorized"),
+    ),
+)]
 #[delete("/user")]
 pub async fn delete_user(
     app_state: web::Data<AppState>,