0.7.0

Добавлена OpenAPI документация эндпоинтов и структур с интерфейсом RapiDoc.

Добавлены derive макросы для преобразования структуры в HttpResponse с помощью ResponderJson и IResponse<T> с помощью IntoIResponse.

Ревью кода эндпоинтов связанных с авторизацией.

Эндпоинт users/me теперь объект пользователя в требуемом виде.

src/database/models.rs

@@ -1,7 +1,17 @@
+use actix_macros::ResponderJson;
 use diesel::prelude::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(diesel_derive_enum::DbEnum, Serialize, Deserialize, Debug, Clone, Copy, PartialEq)]
+#[derive(
+    diesel_derive_enum::DbEnum,
+    Serialize,
+    Deserialize,
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    utoipa::ToSchema,
+)]
 #[ExistingTypePath = "crate::database::schema::sql_types::UserRole"]
 #[DbValueStyle = "UPPERCASE"]
 #[serde(rename_all = "UPPERCASE")]
@@ -11,7 +21,17 @@ pub enum UserRole {
     Admin,
 }
 
-#[derive(Identifiable, AsChangeset, Queryable, Selectable, Serialize, Insertable, Debug)]
+#[derive(
+    Identifiable,
+    AsChangeset,
+    Queryable,
+    Selectable,
+    Serialize,
+    Insertable,
+    Debug,
+    utoipa::ToSchema,
+    ResponderJson,
+)]
 #[diesel(table_name = crate::database::schema::users)]
 #[diesel(treat_none_as_null = true)]
 pub struct User {
@@ -23,4 +43,4 @@ pub struct User {
     pub group: String,
     pub role: UserRole,
     pub version: String,
-}
+}

src/main.rs

@@ -3,8 +3,10 @@ use crate::middlewares::authorization::Authorization;
 use crate::routes::auth::sign_in::{sign_in_default, sign_in_vk};
 use crate::routes::auth::sign_up::{sign_up_default, sign_up_vk};
 use crate::routes::users::me::me;
-use actix_web::{web, App, HttpServer};
+use actix_web::{App, HttpServer};
 use dotenvy::dotenv;
+use utoipa_actix_web::AppExt;
+use utoipa_rapidoc::RapiDoc;
 
 mod app_state;
 
@@ -29,23 +31,37 @@ async fn main() {
     env_logger::init();
 
     HttpServer::new(move || {
-        let auth_scope = web::scope("/auth")
+        let auth_scope = utoipa_actix_web::scope("/auth")
             .service(sign_in_default)
             .service(sign_in_vk)
             .service(sign_up_default)
             .service(sign_up_vk);
 
-        let users_scope = web::scope("/users")
+        let users_scope = utoipa_actix_web::scope("/users")
             .wrap(Authorization)
             .service(me);
 
-        let api_scope = web::scope("/api/v1")
+        let api_scope = utoipa_actix_web::scope("/api/v1")
             .service(auth_scope)
             .service(users_scope);
 
-        App::new().app_data(app_state()).service(api_scope)
+        let (app, api) = App::new()
+            .into_utoipa_app()
+            .app_data(app_state())
+            .service(api_scope)
+            .split_for_parts();
+
+        let rapidoc_service = RapiDoc::with_openapi("/api-docs-json", api).path("/api-docs");
+
+        // Because CORS error on non-localhost
+        let patched_rapidoc_html = rapidoc_service.to_html().replace(
+            "https://unpkg.com/rapidoc/dist/rapidoc-min.js",
+            "https://cdn.jsdelivr.net/npm/rapidoc/dist/rapidoc-min.min.js",
+        );
+
+        app.service(rapidoc_service.custom_html(patched_rapidoc_html))
     })
-    .bind(("127.0.0.1", 8080))
+    .bind(("0.0.0.0", 8080))
     .unwrap()
     .run()
     .await

src/routes/auth/sign_in.rs

@@ -2,8 +2,9 @@ use self::schema::*;
 use crate::database::driver;
 use crate::database::models::User;
 use crate::routes::auth::shared::parse_vk_id;
-use crate::routes::auth::sign_in::schema::ErrorCode;
 use crate::routes::auth::sign_in::schema::SignInData::{Default, Vk};
+use crate::routes::schema::user::UserResponse;
+use crate::routes::schema::ResponseError;
 use crate::{utility, AppState};
 use actix_web::{post, web};
 use diesel::SaveChangesDsl;
@@ -22,11 +23,11 @@ async fn sign_in(data: SignInData, app_state: &web::Data<AppState>) -> Response
                 match bcrypt::verify(&data.password, &user.password) {
                     Ok(result) => {
                         if !result {
-                            return Response::err(ErrorCode::IncorrectCredentials);
+                            return ErrorCode::IncorrectCredentials.into();
                         }
                     }
                     Err(_) => {
-                        return Response::err(ErrorCode::IncorrectCredentials);
+                        return ErrorCode::IncorrectCredentials.into();
                     }
                 }
             }
@@ -39,36 +40,46 @@ async fn sign_in(data: SignInData, app_state: &web::Data<AppState>) -> Response
             user.save_changes::<User>(conn)
                 .expect("Failed to update user");
 
-            Response::ok(&user)
+            UserResponse::from(&user).into()
         }
 
-        Err(_) => Response::err(ErrorCode::IncorrectCredentials),
+        Err(_) => ErrorCode::IncorrectCredentials.into(),
     }
 }
 
+#[utoipa::path(responses(
+    (status = OK, body = UserResponse),
+    (status = NOT_ACCEPTABLE, body = ResponseError<ErrorCode>)
+))]
 #[post("/sign-in")]
 pub async fn sign_in_default(data: Json<Request>, app_state: web::Data<AppState>) -> Response {
     sign_in(Default(data.into_inner()), &app_state).await
 }
 
+#[utoipa::path(responses(
+    (status = OK, body = UserResponse),
+    (status = NOT_ACCEPTABLE, body = ResponseError<ErrorCode>)
+))]
 #[post("/sign-in-vk")]
 pub async fn sign_in_vk(data_json: Json<vk::Request>, app_state: web::Data<AppState>) -> Response {
     let data = data_json.into_inner();
 
     match parse_vk_id(&data.access_token) {
         Ok(id) => sign_in(Vk(id), &app_state).await,
-        Err(_) => Response::err(ErrorCode::InvalidVkAccessToken),
+        Err(_) => ErrorCode::InvalidVkAccessToken.into(),
     }
 }
 
 mod schema {
-    use crate::database::models::User;
-    use crate::routes::schema::{user, ErrorToHttpCode, IResponse};
+    use crate::routes::schema::user::UserResponse;
+    use crate::routes::schema::{HttpStatusCode, IResponse};
     use actix_web::http::StatusCode;
     use serde::{Deserialize, Serialize};
 
-    #[derive(Deserialize, Serialize)]
+    #[derive(Deserialize, Serialize, utoipa::ToSchema)]
+    #[schema(as = SignIn::Request)]
     pub struct Request {
+        #[schema(examples("n08i40k"))]
         pub username: String,
         pub password: String,
     }
@@ -76,44 +87,26 @@ mod schema {
     pub mod vk {
         use serde::{Deserialize, Serialize};
 
-        #[derive(Serialize, Deserialize)]
+        #[derive(Serialize, Deserialize, utoipa::ToSchema)]
         #[serde(rename_all = "camelCase")]
+        #[schema(as = SignInVk::Request)]
         pub struct Request {
             pub access_token: String,
         }
     }
 
-    pub type Response = IResponse<user::ResponseOk, ResponseErr>;
+    pub type Response = IResponse<UserResponse, ErrorCode>;
 
-    #[derive(Serialize)]
-    pub struct ResponseErr {
-        code: ErrorCode,
-    }
-
-    #[derive(Serialize)]
+    #[derive(Serialize, utoipa::ToSchema, Clone)]
     #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+    #[schema(as = SignIn::ErrorCode)]
     pub enum ErrorCode {
         IncorrectCredentials,
         InvalidVkAccessToken,
     }
 
-    pub trait ResponseExt {
-        fn ok(user: &User) -> Self;
-        fn err(code: ErrorCode) -> Response;
-    }
-
-    impl ResponseExt for Response {
-        fn ok(user: &User) -> Self {
-            IResponse(Ok(user::ResponseOk::from_user(&user)))
-        }
-
-        fn err(code: ErrorCode) -> Response {
-            IResponse(Err(ResponseErr { code }))
-        }
-    }
-
-    impl ErrorToHttpCode for ResponseErr {
-        fn to_http_status_code(&self) -> StatusCode {
+    impl HttpStatusCode for ErrorCode {
+        fn status_code(&self) -> StatusCode {
             StatusCode::NOT_ACCEPTABLE
         }
     }
@@ -134,13 +127,13 @@ mod tests {
     use crate::routes::auth::sign_in::sign_in_default;
     use crate::test_env::tests::{static_app_state, test_app_state, test_env};
     use crate::utility;
-    use actix_web::http::StatusCode;
+    use actix_test::test_app;
     use actix_web::dev::ServiceResponse;
     use actix_web::http::Method;
+    use actix_web::http::StatusCode;
     use actix_web::test;
     use sha2::{Digest, Sha256};
     use std::fmt::Write;
-    use actix_test::test_app;
 
     async fn sign_in_client(data: Request) -> ServiceResponse {
         let app = test_app(test_app_state(), sign_in_default).await;

src/routes/auth/sign_up.rs

@@ -3,6 +3,8 @@ use crate::AppState;
 use crate::database::driver;
 use crate::database::models::UserRole;
 use crate::routes::auth::shared::{Error, parse_vk_id};
+use crate::routes::schema::ResponseError;
+use crate::routes::schema::user::UserResponse;
 use actix_web::{post, web};
 use rand::{Rng, rng};
 use web::Json;
@@ -10,7 +12,7 @@ use web::Json;
 async fn sign_up(data: SignUpData, app_state: &web::Data<AppState>) -> Response {
     // If user selected forbidden role.
     if data.role == UserRole::Admin {
-        return Response::err(ErrorCode::DisallowedRole);
+        return ErrorCode::DisallowedRole.into();
     }
 
     // If specified group doesn't exist in schedule.
@@ -18,28 +20,32 @@ async fn sign_up(data: SignUpData, app_state: &web::Data<AppState>) -> Response
 
     if let Some(schedule) = &*schedule_opt {
         if !schedule.data.groups.contains_key(&data.group) {
-            return Response::err(ErrorCode::InvalidGroupName);
+            return ErrorCode::InvalidGroupName.into();
         }
     }
 
     // If user with specified username already exists.
     if driver::users::contains_by_username(&app_state.database, &data.username) {
-        return Response::err(ErrorCode::UsernameAlreadyExists);
+        return ErrorCode::UsernameAlreadyExists.into();
     }
 
     // If user with specified VKID already exists.
     if let Some(id) = data.vk_id {
         if driver::users::contains_by_vk_id(&app_state.database, id) {
-            return Response::err(ErrorCode::VkAlreadyExists);
+            return ErrorCode::VkAlreadyExists.into();
         }
     }
 
-    let user = data.to_user();
+    let user = data.into();
     driver::users::insert(&app_state.database, &user).unwrap();
 
-    Response::ok(&user)
+    UserResponse::from(&user).into()
 }
 
+#[utoipa::path(responses(
+    (status = OK, body = UserResponse),
+    (status = NOT_ACCEPTABLE, body = ResponseError<ErrorCode>)
+))]
 #[post("/sign-up")]
 pub async fn sign_up_default(data_json: Json<Request>, app_state: web::Data<AppState>) -> Response {
     let data = data_json.into_inner();
@@ -58,8 +64,15 @@ pub async fn sign_up_default(data_json: Json<Request>, app_state: web::Data<AppS
     .await
 }
 
+#[utoipa::path(responses(
+    (status = OK, body = UserResponse),
+    (status = NOT_ACCEPTABLE, body = ResponseError<ErrorCode>)
+))]
 #[post("/sign-up-vk")]
-pub async fn sign_up_vk(data_json: Json<vk::Request>, app_state: web::Data<AppState>) -> Response {
+pub async fn sign_up_vk(
+    data_json: Json<vk::Request>,
+    app_state: web::Data<AppState>,
+) -> Response {
     let data = data_json.into_inner();
 
     match parse_vk_id(&data.access_token) {
@@ -87,14 +100,15 @@ pub async fn sign_up_vk(data_json: Json<vk::Request>, app_state: web::Data<AppSt
                 eprintln!("{:?}", err);
             }
 
-            Response::err(ErrorCode::InvalidVkAccessToken)
+            ErrorCode::InvalidVkAccessToken.into()
         }
     }
 }
 
 mod schema {
     use crate::database::models::{User, UserRole};
-    use crate::routes::schema::{ErrorToHttpCode, IResponse, user};
+    use crate::routes::schema::user::UserResponse;
+    use crate::routes::schema::{HttpStatusCode, IResponse};
     use crate::utility;
     use actix_web::http::StatusCode;
     use objectid::ObjectId;
@@ -102,12 +116,20 @@ mod schema {
 
     /// WEB
 
-    #[derive(Serialize, Deserialize)]
+    #[derive(Serialize, Deserialize, utoipa::ToSchema)]
+    #[schema(as = SignUp::Request)]
     pub struct Request {
+        #[schema(examples("n08i40k"))]
         pub username: String,
+
         pub password: String,
+
+        #[schema(examples("ИС-214/23"))]
         pub group: String,
+
         pub role: UserRole,
+
+        #[schema(examples("3.0.0"))]
         pub version: String,
     }
 
@@ -115,34 +137,30 @@ mod schema {
         use crate::database::models::UserRole;
         use serde::{Deserialize, Serialize};
 
-        #[derive(Serialize, Deserialize)]
+        #[derive(Serialize, Deserialize, utoipa::ToSchema)]
         #[serde(rename_all = "camelCase")]
+        #[schema(as = SignUpVk::Request)]
         pub struct Request {
             pub access_token: String,
+
+            #[schema(examples("n08i40k"))]
             pub username: String,
+
+            #[schema(examples("ИС-214/23"))]
             pub group: String,
+
             pub role: UserRole,
+
+            #[schema(examples("3.0.0"))]
             pub version: String,
         }
     }
 
-    pub type Response = IResponse<user::ResponseOk, ResponseErr>;
+    pub type Response = IResponse<UserResponse, ErrorCode>;
 
-    #[derive(Serialize)]
-    #[serde(rename_all = "camelCase")]
-    pub struct ResponseOk {
-        id: String,
-        access_token: String,
-        group: String,
-    }
-
-    #[derive(Serialize)]
-    pub struct ResponseErr {
-        code: ErrorCode,
-    }
-
-    #[derive(Serialize)]
+    #[derive(Clone, Serialize, utoipa::ToSchema)]
     #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+    #[schema(as = SignUp::ErrorCode)]
     pub enum ErrorCode {
         DisallowedRole,
         InvalidGroupName,
@@ -151,23 +169,8 @@ mod schema {
         VkAlreadyExists,
     }
 
-    pub trait ResponseExt {
-        fn ok(user: &User) -> Self;
-        fn err(code: ErrorCode) -> Self;
-    }
-
-    impl ResponseExt for Response {
-        fn ok(user: &User) -> Self {
-            IResponse(Ok(user::ResponseOk::from_user(&user)))
-        }
-
-        fn err(code: ErrorCode) -> Response {
-            Self(Err(ResponseErr { code }))
-        }
-    }
-
-    impl ErrorToHttpCode for ResponseErr {
-        fn to_http_status_code(&self) -> StatusCode {
+    impl HttpStatusCode for ErrorCode {
+        fn status_code(&self) -> StatusCode {
             StatusCode::NOT_ACCEPTABLE
         }
     }
@@ -183,8 +186,8 @@ mod schema {
         pub version: String,
     }
 
-    impl SignUpData {
-        pub fn to_user(self) -> User {
+    impl Into<User> for SignUpData {
+        fn into(self) -> User {
             let id = ObjectId::new().unwrap().to_string();
             let access_token = utility::jwt::encode(&id);
 
@@ -209,11 +212,11 @@ mod tests {
     use crate::routes::auth::sign_up::schema::Request;
     use crate::routes::auth::sign_up::sign_up_default;
     use crate::test_env::tests::{static_app_state, test_app_state, test_env};
-    use actix_web::http::StatusCode;
+    use actix_test::test_app;
     use actix_web::dev::ServiceResponse;
     use actix_web::http::Method;
+    use actix_web::http::StatusCode;
     use actix_web::test;
-    use actix_test::test_app;
 
     struct SignUpPartial {
         username: String,

src/routes/schema.rs

@@ -3,32 +3,68 @@ use actix_web::error::JsonPayloadError;
 use actix_web::http::StatusCode;
 use actix_web::{HttpRequest, HttpResponse, Responder};
 use serde::{Serialize, Serializer};
+use utoipa::PartialSchema;
 
-pub struct IResponse<T: Serialize, E: Serialize>(pub Result<T, E>);
+pub struct IResponse<T, E>(pub Result<T, E>)
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode;
 
-pub trait ErrorToHttpCode {
-    fn to_http_status_code(&self) -> StatusCode;
+impl<T, E> Into<Result<T, E>> for IResponse<T, E>
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode,
+{
+    fn into(self) -> Result<T, E> {
+        self.0
+    }
 }
 
-impl<T: Serialize, E: Serialize> IResponse<T, E> {
+impl<T, E> From<E> for IResponse<T, E>
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode,
+{
+    fn from(value: E) -> Self {
+        IResponse(Err(value))
+    }
+}
+
+pub trait HttpStatusCode {
+    fn status_code(&self) -> StatusCode;
+}
+
+impl<T, E> IResponse<T, E>
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode,
+{
     pub fn new(result: Result<T, E>) -> Self {
         IResponse(result)
     }
 }
 
-impl<T: Serialize, E: Serialize> Serialize for IResponse<T, E> {
+impl<T, E> Serialize for IResponse<T, E>
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode,
+{
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
     {
         match &self.0 {
             Ok(ok) => serializer.serialize_some::<T>(&ok),
-            Err(err) => serializer.serialize_some::<E>(&err),
+            Err(err) => serializer.serialize_some::<ResponseError<E>>(&ResponseError::new(err)),
         }
     }
 }
 
-impl<T: Serialize, E: Serialize + ErrorToHttpCode> Responder for IResponse<T, E> {
+impl<T, E> Responder for IResponse<T, E>
+where
+    T: Serialize + PartialSchema,
+    E: Serialize + PartialSchema + Clone + HttpStatusCode,
+{
     type Body = EitherBody<String>;
 
     fn respond_to(self, _: &HttpRequest) -> HttpResponse<Self::Body> {
@@ -36,7 +72,7 @@ impl<T: Serialize, E: Serialize + ErrorToHttpCode> Responder for IResponse<T, E>
             Ok(body) => {
                 let code = match &self.0 {
                     Ok(_) => StatusCode::OK,
-                    Err(e) => e.to_http_status_code(),
+                    Err(e) => e.status_code(),
                 };
 
                 match HttpResponse::build(code)
@@ -55,24 +91,50 @@ impl<T: Serialize, E: Serialize + ErrorToHttpCode> Responder for IResponse<T, E>
     }
 }
 
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct ResponseError<T: Serialize + PartialSchema> {
+    code: T,
+}
+
+impl<T: Serialize + PartialSchema + Clone> ResponseError<T> {
+    fn new(status_code: &T) -> Self {
+        ResponseError {
+            code: status_code.clone(),
+        }
+    }
+}
+
 pub mod user {
     use crate::database::models::{User, UserRole};
+    use actix_macros::{IntoIResponse, ResponderJson};
     use serde::Serialize;
 
-    #[derive(Serialize)]
+    #[derive(Serialize, utoipa::ToSchema, IntoIResponse, ResponderJson)]
     #[serde(rename_all = "camelCase")]
-    pub struct ResponseOk {
+    pub struct UserResponse {
+        #[schema(examples("67dcc9a9507b0000772744a2"))]
         id: String,
+
+        #[schema(examples("n08i40k"))]
         username: String,
+
+        #[schema(examples("ИС-214/23"))]
         group: String,
+
         role: UserRole,
+
+        #[schema(examples(498094647, json!(null)))]
         vk_id: Option<i32>,
+
+        #[schema(examples(
+            "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjY3ZGNjOWE5NTA3YjAwMDA3NzI3NDRhMiIsImlhdCI6IjE3NDMxMDgwOTkiLCJleHAiOiIxODY5MjUyMDk5In0.rMgXRb3JbT9AvLK4eiY9HMB5LxgUudkpQyoWKOypZFY"
+        ))]
         access_token: String,
     }
 
-    impl ResponseOk {
-        pub fn from_user(user: &User) -> Self {
-            ResponseOk {
+    impl From<&User> for UserResponse {
+        fn from(user: &User) -> Self {
+            UserResponse {
                 id: user.id.clone(),
                 username: user.username.clone(),
                 group: user.group.clone(),
@@ -82,4 +144,17 @@ pub mod user {
             }
         }
     }
+
+    impl From<User> for UserResponse {
+        fn from(user: User) -> Self {
+            UserResponse {
+                id: user.id,
+                username: user.username,
+                group: user.group,
+                role: user.role,
+                vk_id: user.vk_id,
+                access_token: user.access_token,
+            }
+        }
+    }
 }

src/routes/users/me.rs

@@ -1,11 +1,10 @@
-use crate::app_state::AppState;
 use crate::database::models::User;
 use crate::extractors::base::SyncExtractor;
-use actix_web::{HttpResponse, Responder, get, web};
+use actix_web::get;
+use crate::routes::schema::user::UserResponse;
 
+#[utoipa::path(responses((status = OK, body = UserResponse)))]
 #[get("/me")]
-pub async fn me(user: SyncExtractor<User>, app_state: web::Data<AppState>) -> impl Responder {
-    HttpResponse::Ok().json(user.into_inner())
+pub async fn me(user: SyncExtractor<User>) -> UserResponse {
+    user.into_inner().into()
 }
-
-mod schema {}