feat: add documentation crate and integrate OpenAPI specifications

- Added a new crate `doc` for API documentation. - Integrated `utoipa` for OpenAPI support in the presentation layer. - Updated routes to include social features (follow, unfollow, etc.) and diary export. - Enhanced API request and response structures with new DTOs for social interactions. - Updated `Cargo.toml` files to include new dependencies and features. - Modified Dockerfile to copy the new documentation crate. - Refactored existing handlers and routes to accommodate new API endpoints. - Updated tests to cover new functionality and ensure proper API behavior.
2026-05-09 21:29:20 +02:00
parent f66f8745c7
commit fa501706cd
16 changed files with 777 additions and 38 deletions
--- a/crates/presentation/Cargo.toml
+++ b/crates/presentation/Cargo.toml
@@ -4,9 +4,9 @@ version = "0.1.0"
 edition = "2024"

 [dependencies]
-axum = { version = "0.8.8", features = ["macros"] }
 tower-http = { version = "0.6.8", features = ["fs", "trace", "tracing"] }

+axum = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 anyhow = { workspace = true }
@@ -33,6 +33,8 @@ template-askama = { workspace = true }
 event-publisher = { workspace = true }
 rss = { workspace = true }
 export = { workspace = true }
+doc = { workspace = true }
+utoipa = { version = "5.5.0", features = ["axum_extras", "uuid"] }
 infer = "0.19.0"
 percent-encoding = "2"

--- a/crates/presentation/src/dtos.rs
+++ b/crates/presentation/src/dtos.rs
@@ -18,7 +18,8 @@ where
    }
 }

-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::IntoParams)]
+#[into_params(parameter_in = Query)]
 pub struct DiaryQueryParams {
    pub limit: Option<u32>,
    pub offset: Option<u32>,
@@ -66,7 +67,7 @@ pub struct DeleteRedirectForm {
    pub redirect_after: Option<String>,
 }

-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct LogReviewRequest {
    pub external_metadata_id: Option<String>,
    pub manual_title: Option<String>,
@@ -77,7 +78,7 @@ pub struct LogReviewRequest {
    pub watched_at: String,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct MovieDto {
    pub id: Uuid,
    pub title: String,
@@ -86,7 +87,7 @@ pub struct MovieDto {
    pub poster_path: Option<String>,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct ReviewDto {
    pub id: Uuid,
    pub rating: u8,
@@ -94,13 +95,13 @@ pub struct ReviewDto {
    pub watched_at: String,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct DiaryEntryDto {
    pub movie: MovieDto,
    pub review: ReviewDto,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct DiaryResponse {
    pub items: Vec<DiaryEntryDto>,
    pub total_count: u64,
@@ -108,20 +109,20 @@ pub struct DiaryResponse {
    pub offset: u32,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct ReviewHistoryResponse {
    pub movie: MovieDto,
    pub viewings: Vec<ReviewDto>,
    pub trend: String,
 }

-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct LoginRequest {
    pub email: String,
    pub password: String,
 }

-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct LoginResponse {
    pub token: String,
    pub user_id: Uuid,
@@ -129,7 +130,7 @@ pub struct LoginResponse {
    pub expires_at: String,
 }

-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct RegisterRequest {
    pub email: String,
    pub username: String,
@@ -259,8 +260,32 @@ pub struct ProfileQueryParams {
    pub error: Option<String>,
 }

-#[derive(serde::Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct FollowRequest {
+    pub handle: String,
+}
+
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct ActorUrlRequest {
+    pub actor_url: String,
+}
+
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct RemoteActorDto {
+    pub handle: String,
+    pub display_name: Option<String>,
+    pub url: String,
+}
+
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct ActorListResponse {
+    pub actors: Vec<RemoteActorDto>,
+}
+
+#[derive(serde::Deserialize, utoipa::IntoParams)]
+#[into_params(parameter_in = Query)]
 pub struct ExportQueryParams {
+    /// Output format: `csv` (default) or `json`
    #[serde(default = "default_export_format")]
    pub format: String,
 }
--- a/crates/presentation/src/handlers.rs
+++ b/crates/presentation/src/handlers.rs
@@ -862,8 +862,9 @@ pub mod api {

    use crate::{
        dtos::{
-            DiaryEntryDto, DiaryQueryParams, DiaryResponse, ExportQueryParams, LogReviewData,
-            LogReviewRequest, LoginRequest, LoginResponse, MovieDto, RegisterRequest, ReviewDto,
+            ActorListResponse, ActorUrlRequest, DiaryEntryDto, DiaryQueryParams, DiaryResponse,
+            ExportQueryParams, FollowRequest, LogReviewData, LogReviewRequest, LoginRequest,
+            LoginResponse, MovieDto, RegisterRequest, RemoteActorDto, ReviewDto,
            ReviewHistoryResponse,
        },
        errors::ApiError,
@@ -871,6 +872,15 @@ pub mod api {
        state::AppState,
    };

+    #[utoipa::path(
+        get, path = "/api/v1/diary",
+        params(DiaryQueryParams),
+        responses(
+            (status = 200, body = DiaryResponse),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
    pub async fn get_diary(
        State(state): State<AppState>,
        Query(params): Query<DiaryQueryParams>,
@@ -885,6 +895,14 @@ pub mod api {
        }))
    }

+    #[utoipa::path(
+        get, path = "/api/v1/movies/{id}/history",
+        params(("id" = Uuid, Path, description = "Movie ID")),
+        responses(
+            (status = 200, body = ReviewHistoryResponse),
+            (status = 404, description = "Movie not found"),
+        )
+    )]
    pub async fn get_review_history(
        State(state): State<AppState>,
        Path(movie_id): Path<Uuid>,
@@ -904,6 +922,16 @@ pub mod api {
        }))
    }

+    #[utoipa::path(
+        post, path = "/api/v1/reviews",
+        request_body = LogReviewRequest,
+        responses(
+            (status = 201, description = "Review created"),
+            (status = 400, description = "Invalid input"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
    pub async fn post_review(
        State(state): State<AppState>,
        user: AuthenticatedUser,
@@ -914,6 +942,16 @@ pub mod api {
        Ok(StatusCode::CREATED)
    }

+    #[utoipa::path(
+        post, path = "/api/v1/movies/{id}/sync-poster",
+        params(("id" = Uuid, Path, description = "Movie ID")),
+        responses(
+            (status = 204, description = "Poster synced"),
+            (status = 401, description = "Unauthorized"),
+            (status = 404, description = "Movie not found"),
+        ),
+        security(("bearer_auth" = []))
+    )]
    pub async fn sync_poster(
        State(state): State<AppState>,
        _user: AuthenticatedUser,
@@ -948,6 +986,14 @@ pub mod api {
        Ok(StatusCode::NO_CONTENT)
    }

+    #[utoipa::path(
+        post, path = "/api/v1/auth/login",
+        request_body = LoginRequest,
+        responses(
+            (status = 200, body = LoginResponse),
+            (status = 401, description = "Invalid credentials"),
+        )
+    )]
    pub async fn login(
        State(state): State<AppState>,
        Json(req): Json<LoginRequest>,
@@ -968,6 +1014,14 @@ pub mod api {
        }))
    }

+    #[utoipa::path(
+        post, path = "/api/v1/auth/register",
+        request_body = RegisterRequest,
+        responses(
+            (status = 201, description = "User registered"),
+            (status = 400, description = "Invalid input"),
+        )
+    )]
    pub async fn register(
        State(state): State<AppState>,
        Json(req): Json<RegisterRequest>,
@@ -984,6 +1038,17 @@ pub mod api {
        Ok(StatusCode::CREATED)
    }

+    #[utoipa::path(
+        delete, path = "/api/v1/reviews/{id}",
+        params(("id" = Uuid, Path, description = "Review ID")),
+        responses(
+            (status = 204, description = "Review deleted"),
+            (status = 401, description = "Unauthorized"),
+            (status = 403, description = "Forbidden"),
+            (status = 404, description = "Review not found"),
+        ),
+        security(("bearer_auth" = []))
+    )]
    pub async fn delete_review(
        State(state): State<AppState>,
        AuthenticatedUser(user_id): AuthenticatedUser,
@@ -1030,6 +1095,177 @@ pub mod api {
        }
    }

+    fn ap_err(e: anyhow::Error) -> impl IntoResponse {
+        tracing::error!("ActivityPub error: {:?}", e);
+        StatusCode::INTERNAL_SERVER_ERROR
+    }
+
+    #[utoipa::path(
+        get, path = "/api/v1/social/following",
+        responses(
+            (status = 200, body = ActorListResponse),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn get_following(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+    ) -> impl IntoResponse {
+        match state.ap_service.get_following(user.0.value()).await {
+            Ok(actors) => Json(ActorListResponse {
+                actors: actors
+                    .into_iter()
+                    .map(|a| RemoteActorDto {
+                        handle: a.handle,
+                        display_name: a.display_name,
+                        url: a.url,
+                    })
+                    .collect(),
+            })
+            .into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        get, path = "/api/v1/social/followers",
+        responses(
+            (status = 200, body = ActorListResponse),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn get_followers(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+    ) -> impl IntoResponse {
+        match state.ap_service.get_accepted_followers(user.0.value()).await {
+            Ok(actors) => Json(ActorListResponse {
+                actors: actors
+                    .into_iter()
+                    .map(|a| RemoteActorDto {
+                        handle: a.handle,
+                        display_name: a.display_name,
+                        url: a.url,
+                    })
+                    .collect(),
+            })
+            .into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        post, path = "/api/v1/social/follow",
+        request_body = FollowRequest,
+        responses(
+            (status = 200, description = "Follow request sent"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn follow(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+        Json(body): Json<FollowRequest>,
+    ) -> impl IntoResponse {
+        match state.ap_service.follow(user.0.value(), &body.handle).await {
+            Ok(()) => StatusCode::OK.into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        post, path = "/api/v1/social/unfollow",
+        request_body = ActorUrlRequest,
+        responses(
+            (status = 200, description = "Unfollowed"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn unfollow(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+        Json(body): Json<ActorUrlRequest>,
+    ) -> impl IntoResponse {
+        match state.ap_service.unfollow(user.0.value(), &body.actor_url).await {
+            Ok(()) => StatusCode::OK.into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        post, path = "/api/v1/social/followers/accept",
+        request_body = ActorUrlRequest,
+        responses(
+            (status = 200, description = "Follower accepted"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn accept_follower(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+        Json(body): Json<ActorUrlRequest>,
+    ) -> impl IntoResponse {
+        match state.ap_service.accept_follower(user.0.value(), &body.actor_url).await {
+            Ok(()) => StatusCode::OK.into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        post, path = "/api/v1/social/followers/reject",
+        request_body = ActorUrlRequest,
+        responses(
+            (status = 200, description = "Follower rejected"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn reject_follower(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+        Json(body): Json<ActorUrlRequest>,
+    ) -> impl IntoResponse {
+        match state.ap_service.reject_follower(user.0.value(), &body.actor_url).await {
+            Ok(()) => StatusCode::OK.into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        post, path = "/api/v1/social/followers/remove",
+        request_body = ActorUrlRequest,
+        responses(
+            (status = 200, description = "Follower removed"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
+    pub async fn remove_follower(
+        State(state): State<AppState>,
+        user: AuthenticatedUser,
+        Json(body): Json<ActorUrlRequest>,
+    ) -> impl IntoResponse {
+        match state.ap_service.remove_follower(user.0.value(), &body.actor_url).await {
+            Ok(()) => StatusCode::OK.into_response(),
+            Err(e) => ap_err(e).into_response(),
+        }
+    }
+
+    #[utoipa::path(
+        get, path = "/api/v1/diary/export",
+        params(ExportQueryParams),
+        responses(
+            (status = 200, description = "Diary file download", content_type = "text/csv"),
+            (status = 400, description = "Invalid format parameter"),
+            (status = 401, description = "Unauthorized"),
+        ),
+        security(("bearer_auth" = []))
+    )]
    pub async fn export_diary(
        State(state): State<AppState>,
        user: AuthenticatedUser,
--- a/crates/presentation/src/lib.rs
+++ b/crates/presentation/src/lib.rs
@@ -3,6 +3,7 @@ pub mod errors;
 pub mod event_handlers;
 pub mod extractors;
 pub mod handlers;
+pub mod openapi;
 pub mod ports;
 pub mod routes;
 pub mod state;
--- a/crates/presentation/src/main.rs
+++ b/crates/presentation/src/main.rs
@@ -25,7 +25,9 @@ use sqlite::{SqliteMovieRepository, SqliteUserRepository};
 use sqlite_federation::SqliteFederationRepository;
 use template_askama::AskamaHtmlRenderer;

-use presentation::{routes, state::AppState};
+use doc::ApiDocExt;
+use presentation::{openapi::ApiDoc, routes, state::AppState};
+use utoipa::OpenApi as _;

 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -36,7 +38,7 @@ async fn main() -> anyhow::Result<()> {
        .await
        .context("Failed to wire dependencies")?;

-    let app = routes::build_router(state, ap_router);
+    let app = routes::build_router(state, ap_router).with_api_doc(ApiDoc::openapi());

    let host = std::env::var("HOST").unwrap_or_else(|_| "0.0.0.0".to_string());
    let port = std::env::var("PORT").unwrap_or_else(|_| "3000".to_string());
--- a/crates/presentation/src/openapi.rs
+++ b/crates/presentation/src/openapi.rs
@@ -0,0 +1,65 @@
+use utoipa::{
+    Modify, OpenApi,
+    openapi::security::{Http, HttpAuthScheme, SecurityScheme},
+};
+
+use crate::dtos::{
+    ActorListResponse, ActorUrlRequest, DiaryEntryDto, DiaryResponse, FollowRequest, LoginRequest,
+    LoginResponse, LogReviewRequest, MovieDto, RegisterRequest, RemoteActorDto, ReviewDto,
+    ReviewHistoryResponse,
+};
+
+struct SecurityAddon;
+
+impl Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        let components = openapi.components.get_or_insert_with(Default::default);
+        components.add_security_scheme(
+            "bearer_auth",
+            SecurityScheme::Http(Http::new(HttpAuthScheme::Bearer)),
+        );
+    }
+}
+
+#[derive(OpenApi)]
+#[openapi(
+    info(
+        title = "Movies Diary API",
+        version = "1.0.0",
+        description = "REST API for Movies Diary. Authenticate with `POST /api/v1/auth/login` to get a Bearer token."
+    ),
+    paths(
+        crate::handlers::api::get_diary,
+        crate::handlers::api::get_review_history,
+        crate::handlers::api::post_review,
+        crate::handlers::api::delete_review,
+        crate::handlers::api::sync_poster,
+        crate::handlers::api::login,
+        crate::handlers::api::register,
+        crate::handlers::api::export_diary,
+        crate::handlers::api::get_following,
+        crate::handlers::api::get_followers,
+        crate::handlers::api::follow,
+        crate::handlers::api::unfollow,
+        crate::handlers::api::accept_follower,
+        crate::handlers::api::reject_follower,
+        crate::handlers::api::remove_follower,
+    ),
+    components(schemas(
+        DiaryResponse,
+        DiaryEntryDto,
+        MovieDto,
+        ReviewDto,
+        LogReviewRequest,
+        LoginRequest,
+        LoginResponse,
+        RegisterRequest,
+        ReviewHistoryResponse,
+        ActorListResponse,
+        RemoteActorDto,
+        FollowRequest,
+        ActorUrlRequest,
+    )),
+    modifiers(&SecurityAddon),
+)]
+pub struct ApiDoc;
--- a/crates/presentation/src/routes.rs
+++ b/crates/presentation/src/routes.rs
@@ -176,6 +176,13 @@ fn api_routes(rate_limit: u64) -> Router<AppState> {
            .route("/auth/login", routing::post(handlers::api::login))
            .route("/auth/register", routing::post(handlers::api::register))
            .route("/diary/export", routing::get(handlers::api::export_diary))
+            .route("/social/following", routing::get(handlers::api::get_following))
+            .route("/social/followers", routing::get(handlers::api::get_followers))
+            .route("/social/follow", routing::post(handlers::api::follow))
+            .route("/social/unfollow", routing::post(handlers::api::unfollow))
+            .route("/social/followers/accept", routing::post(handlers::api::accept_follower))
+            .route("/social/followers/reject", routing::post(handlers::api::reject_follower))
+            .route("/social/followers/remove", routing::post(handlers::api::remove_follower))
            .route_layer(auth_rate_limit),
    )
 }
--- a/crates/presentation/tests/api_test.rs
+++ b/crates/presentation/tests/api_test.rs
@@ -167,7 +167,7 @@ async fn get_api_diary_returns_empty_list() {
    let response = app
        .oneshot(
            Request::builder()
-                .uri("/api/diary")
+                .uri("/api/v1/diary")
                .body(Body::empty())
                .unwrap(),
        )
@@ -192,7 +192,7 @@ async fn post_api_reviews_without_auth_returns_401() {
        .oneshot(
            Request::builder()
                .method("POST")
-                .uri("/api/reviews")
+                .uri("/api/v1/reviews")
                .header("content-type", "application/json")
                .body(Body::from(
                    r#"{"rating":4,"watched_at":"2026-01-01T20:00:00","manual_title":"Dune","manual_release_year":2021}"#,
@@ -212,7 +212,7 @@ async fn post_api_auth_login_unknown_user_returns_401() {
        .oneshot(
            Request::builder()
                .method("POST")
-                .uri("/api/auth/login")
+                .uri("/api/v1/auth/login")
                .header("content-type", "application/json")
                .body(Body::from(r#"{"email":"a@b.com","password":"x"}"#))
                .unwrap(),