◉ClassyGitshadowzzh

openapi.rs

openapi.rs
//! OpenAPI 文件(utoipa)+ Scalar UI。與 specta 型別同源——typed 回應 struct 同時 derive
//! `specta::Type`(前端 TS)與 `utoipa::ToSchema`(OpenAPI)。
//! 涵蓋全 API 面(120 端點):公開讀 typed 完整 schema、admin/mutation/第三方 proxy
//! path-level(動態 Value 無法 typed)。paths()/schemas() 由 annotations 機械收集。

use axum::Json;
use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme};
use utoipa::{Modify, OpenApi};

use crate::handlers;

/// bearer JWT security scheme——admin/auth 端點的 `security(("bearer" = []))` 指向此。
struct SecurityAddon;
impl Modify for SecurityAddon {
    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
        if let Some(components) = openapi.components.as_mut() {
            components.add_security_scheme(
                "bearer",
                SecurityScheme::Http(
                    HttpBuilder::new().scheme(HttpAuthScheme::Bearer).bearer_format("JWT").build(),
                ),
            );
        }
    }
}

#[derive(OpenApi)]
#[openapi(
    info(
        title = "koimsurai / 宙と木 API",
        description = "個人站 Rust 後端 · 完整 API 面(公開讀 typed、admin/mutation/第三方 proxy path-level)",
        version = "0.2.0",
    ),
    modifiers(&SecurityAddon),
    paths(
        handlers::admin::admin_batch_comment_status,
        handlers::admin::admin_blacklist,
        handlers::admin::admin_categories,
        handlers::admin::admin_comments,
        handlers::admin::admin_create_post,
        handlers::admin::admin_delete_post,
        handlers::admin::admin_restore_post,
        handlers::admin::admin_get_post,
        handlers::admin::admin_keyword_filters,
        handlers::admin::admin_posts,
        handlers::admin::admin_stats,
        handlers::analytics::admin_analytics,
        handlers::admin::admin_tags,
        handlers::admin::admin_update_post,
        handlers::admin::admin_update_user_role,
        handlers::admin::admin_users,
        handlers::admin::create_blacklist,
        handlers::admin::create_category,
        handlers::admin::create_keyword_filter,
        handlers::admin::create_tag,
        handlers::admin::delete_blacklist,
        handlers::admin::delete_category,
        handlers::admin::delete_comment,
        handlers::admin::delete_keyword_filter,
        handlers::admin::delete_tag,
        handlers::admin::patch_comment_status,
        handlers::admin::reply_comment,
        handlers::admin::update_category,
        handlers::admin::update_comment,
        handlers::admin::update_tag,
        handlers::auth::login,
        handlers::auth::logout,
        handlers::auth::me,
        handlers::auth::providers,
        handlers::auth::reset_admin,
        handlers::bahamut::cookie,
        handlers::bahamut::status,
        handlers::books::admin_books,
        handlers::books::book_stats,
        handlers::books::create_book,
        handlers::books::delete_book,
        handlers::books::get_book,
        handlers::books::list_books,
        handlers::books::update_book,
        handlers::categories::list_categories,
        handlers::comments::post_comment,
        handlers::comments::thought_comment,
        handlers::comments::page_comments,
        handlers::comments::page_comment,
        handlers::gallery::gallery_photos,
        handlers::gallery::gallery_sync,
        handlers::photo_meta::admin_photos,
        handlers::photo_meta::admin_update_photo,
        handlers::collection::admin_collection,
        handlers::collection::admin_set_hidden,
        handlers::gallery::image_proxy,
        handlers::home::health,
        handlers::telemetry::telemetry,
        handlers::friends::friends,
        handlers::friend_links::apply,
        handlers::friend_links::admin_friends,
        handlers::friend_links::admin_create_friend,
        handlers::friend_links::admin_update_friend,
        handlers::friend_links::admin_delete_friend,
        handlers::friend_links::admin_check_friend,
        handlers::home::home_digest,
        handlers::mailer::send_newsletter_route,
        handlers::newsletter::by_token,
        handlers::newsletter::subscribe,
        handlers::newsletter::subscribers,
        handlers::newsletter::unsubscribe,
        handlers::oauth::github_callback,
        handlers::oauth::google_callback,
        handlers::og::og_png,
        handlers::opencc::generate_zh_cn,
        handlers::posts::comment_like,
        handlers::posts::get_post,
        handlers::posts::list_posts,
        handlers::posts::patch_post_status,
        handlers::posts::post_comments,
        handlers::posts::post_like,
        handlers::posts::post_reaction,
        handlers::posts::post_reactions,
        handlers::posts::post_unlike,
        handlers::posts::post_view,
        handlers::quote::quote_daily,
        handlers::rss::site_rss,
        handlers::series::list_series,
        handlers::series::series_by_name,
        handlers::spotify::audio_features,
        handlers::spotify::login,
        handlers::spotify::me,
        handlers::spotify::now_playing,
        handlers::spotify::recently_played,
        handlers::spotify::spotify_callback,
        handlers::spotify::top_genres,
        handlers::spotify::top_tracks,
        handlers::stats::site_stats,
        handlers::tags::list_tags,
        handlers::thirdparty::books_search_external,
        handlers::tw_isbn::tw_search,
        handlers::thirdparty::github_events,
        handlers::thirdparty::github_repos,
        handlers::thirdparty::github_works,
        handlers::thirdparty::github_contributions,
        handlers::thirdparty::github_user,
        handlers::thirdparty::steam_achievements,
        handlers::thirdparty::steam_owned_games,
        handlers::thirdparty::steam_player,
        handlers::thirdparty::steam_profile,
        handlers::thirdparty::steam_recent_games,
        handlers::thirdparty::wakatime_projects,
        handlers::thirdparty::wakatime_today,
        handlers::thirdparty::wakatime_week,
        handlers::thoughts::admin_create_thought,
        handlers::thoughts::admin_delete_thought,
        handlers::thoughts::admin_update_thought,
        handlers::thoughts::get_thought,
        handlers::thoughts::list_thought_comments,
        handlers::thoughts::list_thoughts,
        handlers::thoughts::thought_react,
        handlers::thoughts::thoughts_rss,
        handlers::upload::upload,
        handlers::vitals::report_vital,
        handlers::vitals::vitals_stats,
        handlers::link_preview::link_preview,
        handlers::watch::anime_history,
        handlers::watch::create_favorite,
        handlers::watch::delete_favorite,
        handlers::watch::favorites,
        handlers::watch::films_recent,
        handlers::watch::heartbeat,
        handlers::watch::tmdb_search,
        handlers::watch::tv_recent,
        handlers::watch::update_favorite,
        handlers::watch::watch_now,
        handlers::watch::watch_stats,
    ),
    components(schemas(
        handlers::telemetry::Telemetry,
        handlers::friends::FriendStar,
        handlers::friends::FriendPost,
        handlers::friend_links::FriendCheck,
        handlers::friend_links::AdminFriendRow,
        handlers::friend_links::FriendCounts,
        handlers::friend_links::AdminFriendsResponse,
        handlers::analytics::AnalyticsTotals,
        handlers::analytics::AnalyticsPoint,
        handlers::analytics::AnalyticsRow,
        handlers::analytics::AnalyticsResponse,
        handlers::friend_links::ApplyBody,
        handlers::friend_links::CreateFriendBody,
        handlers::friend_links::UpdateFriendBody,
        handlers::admin::AdminCategoryRow,
        handlers::admin::AdminCommentRow,
        handlers::admin::AdminCommentsResponse,
        handlers::admin::AdminPostDetailResponse,
        handlers::admin::AdminPostFull,
        handlers::admin::AdminPostsResponse,
        handlers::admin::AdminTagRow,
        handlers::admin::AdminUserRow,
        handlers::admin::AdminUsersResponse,
        handlers::admin::BlacklistBody,
        handlers::admin::BlacklistResponse,
        handlers::admin::BlacklistRow,
        handlers::admin::CategoryBody,
        handlers::admin::CategoryCreated,
        handlers::admin::CategoryDeleted,
        handlers::admin::CategoryUpdated,
        handlers::admin::CommentCounts,
        handlers::admin::ContentBody,
        handlers::admin::CreatedResponse,
        handlers::admin::ErrorResponse,
        handlers::admin::MessageResponse,
        handlers::admin::TagCreated,
        handlers::admin::TagUpdated,
        handlers::admin::KeywordBody,
        handlers::admin::KeywordFilterRow,
        handlers::admin::KeywordFiltersResponse,
        handlers::admin::StatusBody,
        handlers::admin::TagBody,
        handlers::auth::LoginBody,
        handlers::auth::ResetAdminBody,
        handlers::books::BookDetailResponse,
        handlers::books::BookRow,
        handlers::books::BooksListResponse,
        handlers::categories::CategoriesResponse,
        handlers::categories::CategoryRow,
        handlers::comments::CommentBody,
        handlers::home::DigestComment,
        handlers::home::DigestPost,
        handlers::home::DigestResponse,
        handlers::home::DigestThought,
        handlers::home::DigestTimeline,
        handlers::newsletter::SubscribeBody,
        handlers::newsletter::SubscriberByToken,
        handlers::newsletter::SubscriberRow,
        handlers::newsletter::SubscribersResponse,
        handlers::newsletter::UnsubscribeBody,
        handlers::posts::CommentRow,
        handlers::posts::CommentsResponse,
        handlers::posts::Pagination,
        handlers::posts::PostDetailResponse,
        handlers::posts::PostListItem,
        handlers::posts::PostsListResponse,
        handlers::posts::ReactionBody,
        handlers::posts::ReactionRow,
        handlers::posts::ReactionsResponse,
        handlers::posts::StatusBody,
        handlers::series::SeriesDetailResponse,
        handlers::series::SeriesListResponse,
        handlers::series::SeriesPostRow,
        handlers::series::SeriesRow,
        handlers::stats::StatsResponse,
        handlers::tags::TagRow,
        handlers::tags::TagsResponse,
        handlers::thoughts::AdminThoughtBody,
        handlers::thoughts::ReactBody,
        handlers::thoughts::ThoughtDetailResponse,
        handlers::thoughts::ThoughtOut,
        handlers::thoughts::ThoughtsListResponse,
        handlers::vitals::VitalBeacon,
        handlers::link_preview::LinkPreviewResponse,
        handlers::watch::AnimeHistoryResponse,
        handlers::watch::AnimeRow,
        handlers::watch::FilmRow,
        handlers::watch::FilmsResponse,
        handlers::watch::TvResponse,
        handlers::watch::TvRow,
        handlers::watch::WatchStatsResponse,
    )),
    tags(
        (name = "admin", description = "後台管理(需 bearer)"),
        (name = "auth", description = "認證(登入/session/OAuth)"),
        (name = "books", description = "書櫃"),
        (name = "categories", description = "分類"),
        (name = "gallery", description = "相簿"),
        (name = "home", description = "首頁/健康檢查"),
        (name = "integrations", description = "第三方整合(Spotify/Steam/GitHub/WakaTime)"),
        (name = "media", description = "媒體(OG 圖等)"),
        (name = "misc", description = "雜項(quote/rss/vitals 等)"),
        (name = "newsletter", description = "電子報"),
        (name = "posts", description = "文章"),
        (name = "series", description = "系列文"),
        (name = "stats", description = "站台統計"),
        (name = "tags", description = "標籤"),
        (name = "thoughts", description = "碎念"),
        (name = "watch", description = "在看什麼"),
    ),
)]
pub struct ApiDoc;

/// `GET /api/openapi.json` —— 機器可讀 OpenAPI 3.1 spec(完全自架)。
/// UI(Scalar)由 utoipa-scalar 整合在 main.rs 掛 `/api/docs`(axum 0.8 後可原生 merge)。
pub async fn openapi_json() -> Json<utoipa::openapi::OpenApi> {
    Json(ApiDoc::openapi())
}