feature: support openapi spec

tyr-rust-bootcamp · May 4, 2024 · a8f3ef3 · a8f3ef3
1 parent 848b6fb
commit a8f3ef3
Show file tree

Hide file tree

Showing 13 changed files with 329 additions and 14 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/chat_core/Cargo.toml b/chat_core/Cargo.toml
@@ -14,5 +14,6 @@ sqlx = { workspace = true }
 tokio = { workspace = true }
 tower = { workspace = true }
 tower-http = { workspace = true }
-tracing.workspace = true
+tracing = { workspace = true }
+utoipa = { version = "4.2.0", features = ["axum_extras", "chrono"] }
 uuid = { version = "1.8.0", features = ["v7", "serde"] }
diff --git a/chat_core/src/lib.rs b/chat_core/src/lib.rs
@@ -7,8 +7,9 @@ use serde::{Deserialize, Serialize};
 use sqlx::FromRow;
 
 pub use utils::*;
+use utoipa::ToSchema;
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, FromRow, ToSchema, Serialize, Deserialize, PartialEq)]
 pub struct User {
     pub id: i64,
     pub ws_id: i64,
@@ -20,22 +21,22 @@ pub struct User {
     pub created_at: DateTime<Utc>,
 }
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, FromRow, ToSchema, Serialize, Deserialize, PartialEq)]
 pub struct Workspace {
     pub id: i64,
     pub name: String,
     pub owner_id: i64,
     pub created_at: DateTime<Utc>,
 }
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, FromRow, ToSchema, Serialize, Deserialize, PartialEq)]
 pub struct ChatUser {
     pub id: i64,
     pub fullname: String,
     pub email: String,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, PartialOrd, sqlx::Type)]
+#[derive(Debug, Clone, ToSchema, Serialize, Deserialize, PartialEq, PartialOrd, sqlx::Type)]
 #[sqlx(type_name = "chat_type", rename_all = "snake_case")]
 #[serde(rename_all = "snake_case")]
 pub enum ChatType {
@@ -45,7 +46,7 @@ pub enum ChatType {
     PublicChannel,
 }
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, FromRow, ToSchema, Serialize, Deserialize, PartialEq)]
 pub struct Chat {
     pub id: i64,
     pub ws_id: i64,
@@ -55,7 +56,7 @@ pub struct Chat {
     pub created_at: DateTime<Utc>,
 }
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, FromRow, ToSchema, Serialize, Deserialize, PartialEq)]
 pub struct Message {
     pub id: i64,
     pub chat_id: i64,

diff --git a/chat_server/Cargo.toml b/chat_server/Cargo.toml
@@ -30,6 +30,10 @@ tower = { workspace = true }
 tower-http = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
+utoipa = { version = "4.2.0", features = ["axum_extras", "chrono"] }
+utoipa-swagger-ui = { version = "6.0.0", features = ["axum"] }
+utoipa-redoc = { version = "3.0.0", features = ["axum"] }
+utoipa-rapidoc = { version = "3.0.0", features = ["axum"] }
 
 [dev-dependencies]
 chat-server = { workspace = true, features = ["test-util"] }
diff --git a/chat_server/src/error.rs b/chat_server/src/error.rs
@@ -3,8 +3,9 @@ use axum::response::Json;
 use axum::response::{IntoResponse, Response};
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
+use utoipa::ToSchema;
 
-#[derive(Debug, Serialize, Deserialize)]
+#[derive(Debug, ToSchema, Serialize, Deserialize)]
 pub struct ErrorOutput {
     pub error: String,
 }

diff --git a/chat_server/src/handlers/auth.rs b/chat_server/src/handlers/auth.rs
@@ -4,12 +4,25 @@ use crate::{
 };
 use axum::{extract::State, http::StatusCode, response::IntoResponse, Json};
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
-#[derive(Debug, Serialize, Deserialize)]
+#[derive(Debug, Serialize, ToSchema, Deserialize)]
 pub struct AuthOutput {
     token: String,
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/signup",
+    responses(
+        (status = 200, description = "User created", body = AuthOutput),
+    )
+)]
+/// Create a new user in the chat system with email and password.
+///
+/// - If the email already exists, it will return 409.
+/// - Otherwise, it will return 201 with a token.
+/// - If the workspace doesn't exist, it will create one.
 pub(crate) async fn signup_handler(
     State(state): State<AppState>,
     Json(input): Json<CreateUser>,
@@ -20,6 +33,13 @@ pub(crate) async fn signup_handler(
     Ok((StatusCode::CREATED, body))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/signin",
+    responses(
+        (status = 200, description = "User signed in", body = AuthOutput),
+    )
+)]
 pub(crate) async fn signin_handler(
     State(state): State<AppState>,
     Json(input): Json<SigninUser>,