//! 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())
}