julienfroidefond/stripstream-librarian
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

add OpenAPI/Swagger documentation with utoipa

Browse Source
This commit is contained in:
Julien Froidefond
2026-03-05 21:46:29 +01:00
parent ef8a755a83
commit 40b7200bb3
11 changed files with 450 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
apps/api/src/books.rs
View File

@@ -3,18 +3,22 @@ use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sqlx::Row;
use uuid::Uuid;
use utoipa::ToSchema;
use crate::{error::ApiError, AppState};
#[derive(Deserialize)]
#[derive(Deserialize, ToSchema)]
pub struct ListBooksQuery {
#[schema(value_type = Option<String>)]
pub library_id: Option<Uuid>,
#[schema(value_type = Option<String>)]
pub kind: Option<String>,
pub cursor: Option<Uuid>,
#[schema(value_type = Option<i64>, example = 50)]
pub limit: Option<i64>,
}
#[derive(Serialize)]
#[derive(Serialize, ToSchema)]
pub struct BookItem {
pub id: Uuid,
pub library_id: Uuid,
@@ -28,13 +32,13 @@ pub struct BookItem {
pub updated_at: DateTime<Utc>,
}
#[derive(Serialize)]
#[derive(Serialize, ToSchema)]
pub struct BooksPage {
pub items: Vec<BookItem>,
pub next_cursor: Option<Uuid>,
}
#[derive(Serialize)]
#[derive(Serialize, ToSchema)]
pub struct BookDetails {
pub id: Uuid,
pub library_id: Uuid,
@@ -50,6 +54,20 @@ pub struct BookDetails {
pub file_parse_status: Option<String>,
}
#[utoipa::path(
get,
path = "/books",
tag = "books",
params(
("library_id" = Option<Uuid>, Query, description = "Filter by library ID"),
("kind" = Option<String>, Query, description = "Filter by book kind (cbz, cbr, pdf)"),
("cursor" = Option<Uuid>, Query, description = "Cursor for pagination"),
("limit" = Option<i64>, Query, description = "Max items to return (max 200)"),
),
responses(
(status = 200, body = BooksPage),
)
)]
pub async fn list_books(
State(state): State<AppState>,
Query(query): Query<ListBooksQuery>,
@@ -102,6 +120,15 @@ pub async fn list_books(
}))
}
#[utoipa::path(
get,
path = "/books/{id}",
tag = "books",
responses(
(status = 200, body = BookDetails),
(status = 404, description = "Book not found"),
)
)]
pub async fn get_book(
State(state): State<AppState>,
Path(id): Path<Uuid>,

67
apps/api/src/index_jobs.rs
View File

@@ -3,31 +3,51 @@ use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sqlx::Row;
use uuid::Uuid;
use utoipa::ToSchema;
use crate::{error::ApiError, AppState};
#[derive(Deserialize)]
#[derive(Deserialize, ToSchema)]
pub struct RebuildRequest {
#[schema(value_type = Option<String>)]
pub library_id: Option<Uuid>,
}
#[derive(Serialize)]
pub struct IndexJobItem {
#[derive(Serialize, ToSchema)]
pub struct IndexJobResponse {
pub id: Uuid,
#[schema(value_type = Option<String>)]
pub library_id: Option<Uuid>,
pub r#type: String,
pub status: String,
#[schema(value_type = Option<String>)]
pub started_at: Option<DateTime<Utc>>,
#[schema(value_type = Option<String>)]
pub finished_at: Option<DateTime<Utc>>,
pub stats_json: Option<serde_json::Value>,
pub error_opt: Option<String>,
pub created_at: DateTime<Utc>,
}
#[derive(Serialize, ToSchema)]
pub struct FolderItem {
pub name: String,
pub path: String,
}
#[utoipa::path(
post,
path = "/index/rebuild",
tag = "admin",
request_body = Option<RebuildRequest>,
responses(
(status = 200, body = IndexJobResponse),
)
)]
pub async fn enqueue_rebuild(
State(state): State<AppState>,
payload: Option<Json<RebuildRequest>>,
) -> Result<Json<IndexJobItem>, ApiError> {
) -> Result<Json<IndexJobResponse>, ApiError> {
let library_id = payload.and_then(|p| p.0.library_id);
let id = Uuid::new_v4();
@@ -49,7 +69,15 @@ pub async fn enqueue_rebuild(
Ok(Json(map_row(row)))
}
pub async fn list_index_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobItem>>, ApiError> {
#[utoipa::path(
get,
path = "/index/status",
tag = "admin",
responses(
(status = 200, body = Vec<IndexJobResponse>),
)
)]
pub async fn list_index_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobResponse>>, ApiError> {
let rows = sqlx::query(
"SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at FROM index_jobs ORDER BY created_at DESC LIMIT 100",
)
@@ -59,10 +87,19 @@ pub async fn list_index_jobs(State(state): State<AppState>) -> Result<Json<Vec<I
Ok(Json(rows.into_iter().map(map_row).collect()))
}
#[utoipa::path(
post,
path = "/index/cancel/{id}",
tag = "admin",
responses(
(status = 200, body = IndexJobResponse),
(status = 404, description = "Job not found or already finished"),
)
)]
pub async fn cancel_job(
State(state): State<AppState>,
id: axum::extract::Path<Uuid>,
) -> Result<Json<IndexJobItem>, ApiError> {
) -> Result<Json<IndexJobResponse>, ApiError> {
let rows_affected = sqlx::query(
"UPDATE index_jobs SET status = 'cancelled' WHERE id = $1 AND status IN ('pending', 'running')",
)
@@ -84,12 +121,14 @@ pub async fn cancel_job(
Ok(Json(map_row(row)))
}
#[derive(Serialize)]
pub struct FolderItem {
pub name: String,
pub path: String,
}
#[utoipa::path(
get,
path = "/folders",
tag = "admin",
responses(
(status = 200, body = Vec<FolderItem>),
)
)]
pub async fn list_folders(State(_state): State<AppState>) -> Result<Json<Vec<FolderItem>>, ApiError> {
let libraries_path = std::path::Path::new("/libraries");
let mut folders = Vec::new();
@@ -110,8 +149,8 @@ pub async fn list_folders(State(_state): State<AppState>) -> Result<Json<Vec<Fol
Ok(Json(folders))
}
fn map_row(row: sqlx::postgres::PgRow) -> IndexJobItem {
IndexJobItem {
fn map_row(row: sqlx::postgres::PgRow) -> IndexJobResponse {
IndexJobResponse {
id: row.get("id"),
library_id: row.get("library_id"),
r#type: row.get("type"),

48
apps/api/src/libraries.rs
View File

@@ -4,11 +4,12 @@ use axum::{extract::{Path as AxumPath, State}, Json};
use serde::{Deserialize, Serialize};
use sqlx::Row;
use uuid::Uuid;
use utoipa::ToSchema;
use crate::{error::ApiError, AppState};
#[derive(Serialize)]
pub struct LibraryDto {
#[derive(Serialize, ToSchema)]
pub struct LibraryResponse {
pub id: Uuid,
pub name: String,
pub root_path: String,
@@ -16,13 +17,23 @@ pub struct LibraryDto {
pub book_count: i64,
}
#[derive(Deserialize)]
pub struct CreateLibraryInput {
#[derive(Deserialize, ToSchema)]
pub struct CreateLibraryRequest {
#[schema(value_type = String, example = "Comics")]
pub name: String,
#[schema(value_type = String, example = "/data/comics")]
pub root_path: String,
}
pub async fn list_libraries(State(state): State<AppState>) -> Result<Json<Vec<LibraryDto>>, ApiError> {
#[utoipa::path(
get,
path = "/libraries",
tag = "admin",
responses(
(status = 200, body = Vec<LibraryResponse>),
)
)]
pub async fn list_libraries(State(state): State<AppState>) -> Result<Json<Vec<LibraryResponse>>, ApiError> {
let rows = sqlx::query(
"SELECT l.id, l.name, l.root_path, l.enabled,
(SELECT COUNT(*) FROM books b WHERE b.library_id = l.id) as book_count
@@ -33,7 +44,7 @@ pub async fn list_libraries(State(state): State<AppState>) -> Result<Json<Vec<Li
let items = rows
.into_iter()
.map(|row| LibraryDto {
.map(|row| LibraryResponse {
id: row.get("id"),
name: row.get("name"),
root_path: row.get("root_path"),
@@ -45,10 +56,20 @@ pub async fn list_libraries(State(state): State<AppState>) -> Result<Json<Vec<Li
Ok(Json(items))
}
#[utoipa::path(
post,
path = "/libraries",
tag = "admin",
request_body = CreateLibraryRequest,
responses(
(status = 200, body = LibraryResponse),
(status = 400, description = "Invalid input"),
)
)]
pub async fn create_library(
State(state): State<AppState>,
Json(input): Json<CreateLibraryInput>,
) -> Result<Json<LibraryDto>, ApiError> {
Json(input): Json<CreateLibraryRequest>,
) -> Result<Json<LibraryResponse>, ApiError> {
if input.name.trim().is_empty() {
return Err(ApiError::bad_request("name is required"));
}
@@ -66,7 +87,7 @@ pub async fn create_library(
.execute(&state.pool)
.await?;
Ok(Json(LibraryDto {
Ok(Json(LibraryResponse {
id,
name: input.name.trim().to_string(),
root_path,
@@ -75,6 +96,15 @@ pub async fn create_library(
}))
}
#[utoipa::path(
delete,
path = "/libraries/{id}",
tag = "admin",
responses(
(status = 200, description = "Library deleted"),
(status = 404, description = "Library not found"),
)
)]
pub async fn delete_library(
State(state): State<AppState>,
AxumPath(id): AxumPath<Uuid>,

9
apps/api/src/main.rs
View File

@@ -3,6 +3,7 @@ mod books;
mod error;
mod index_jobs;
mod libraries;
mod openapi;
mod pages;
mod search;
mod tokens;
@@ -22,6 +23,8 @@ use axum::{
routing::{delete, get},
Json, Router,
};
use utoipa::OpenApi;
use utoipa_swagger_ui::SwaggerUi;
use lru::LruCache;
use stripstream_core::config::ApiConfig;
use sqlx::postgres::PgPoolOptions;
@@ -118,6 +121,8 @@ async fn main() -> anyhow::Result<()> {
.route("/health", get(health))
.route("/ready", get(ready))
.route("/metrics", get(metrics))
.route("/docs", get(docs_redirect))
.merge(SwaggerUi::new("/swagger-ui").url("/openapi.json", openapi::ApiDoc::openapi()))
.merge(admin_routes)
.merge(read_routes)
.layer(middleware::from_fn_with_state(state.clone(), request_counter))
@@ -133,6 +138,10 @@ async fn health() -> &'static str {
"ok"
}
async fn docs_redirect() -> impl axum::response::IntoResponse {
axum::response::Redirect::to("/swagger-ui/")
}
async fn ready(axum::extract::State(state): axum::extract::State<AppState>) -> Result<Json<serde_json::Value>, error::ApiError> {
sqlx::query("SELECT 1").execute(&state.pool).await?;
Ok(Json(serde_json::json!({"status": "ready"})))

45
apps/api/src/openapi.rs Normal file
View File

@@ -0,0 +1,45 @@
use utoipa::OpenApi;
#[derive(OpenApi)]
#[openapi(
paths(
crate::books::list_books,
crate::books::get_book,
crate::pages::get_page,
crate::search::search_books,
crate::index_jobs::enqueue_rebuild,
crate::index_jobs::list_index_jobs,
crate::index_jobs::cancel_job,
crate::index_jobs::list_folders,
crate::libraries::list_libraries,
crate::libraries::create_library,
crate::libraries::delete_library,
crate::tokens::list_tokens,
crate::tokens::create_token,
crate::tokens::revoke_token,
),
components(
schemas(
crate::books::ListBooksQuery,
crate::books::BookItem,
crate::books::BooksPage,
crate::books::BookDetails,
crate::pages::PageQuery,
crate::search::SearchQuery,
crate::search::SearchResponse,
crate::index_jobs::RebuildRequest,
crate::index_jobs::IndexJobResponse,
crate::index_jobs::FolderItem,
crate::libraries::LibraryResponse,
crate::libraries::CreateLibraryRequest,
crate::tokens::CreateTokenRequest,
crate::tokens::TokenResponse,
crate::tokens::CreatedTokenResponse,
)
),
tags(
(name = "books", description = "Books management endpoints"),
(name = "admin", description = "Admin management endpoints"),
)
)]
pub struct ApiDoc;

23
apps/api/src/pages.rs
View File

@@ -13,16 +13,20 @@ use axum::{
};
use image::{codecs::jpeg::JpegEncoder, codecs::png::PngEncoder, codecs::webp::WebPEncoder, ColorType, ImageEncoder};
use serde::Deserialize;
use utoipa::ToSchema;
use sha2::{Digest, Sha256};
use sqlx::Row;
use uuid::Uuid;
use crate::{error::ApiError, AppState};
#[derive(Deserialize)]
#[derive(Deserialize, ToSchema)]
pub struct PageQuery {
#[schema(value_type = Option<String>, example = "webp")]
pub format: Option<String>,
#[schema(value_type = Option<u8>, example = 80)]
pub quality: Option<u8>,
#[schema(value_type = Option<u32>, example = 1200)]
pub width: Option<u32>,
}
@@ -60,6 +64,23 @@ impl OutputFormat {
}
}
#[utoipa::path(
get,
path = "/books/{book_id}/pages/{n}",
tag = "books",
params(
("book_id" = Uuid, description = "Book UUID"),
("n" = u32, description = "Page number (starts at 1)"),
("format" = Option<String>, Query, description = "Output format: webp, jpeg, png"),
("quality" = Option<u8>, Query, description = "JPEG quality 1-100"),
("width" = Option<u32>, Query, description = "Max width (max 2160)"),
),
responses(
(status = 200, description = "Page image", content_type = "image/webp"),
(status = 400, description = "Invalid parameters"),
(status = 404, description = "Book or page not found"),
)
)]
pub async fn get_page(
State(state): State<AppState>,
AxumPath((book_id, n)): AxumPath<(Uuid, u32)>,

25
apps/api/src/search.rs
View File

@@ -1,24 +1,45 @@
use axum::{extract::{Query, State}, Json};
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;
use crate::{error::ApiError, AppState};
#[derive(Deserialize)]
#[derive(Deserialize, ToSchema)]
pub struct SearchQuery {
#[schema(value_type = String, example = "batman")]
pub q: String,
#[schema(value_type = Option<String>)]
pub library_id: Option<String>,
#[schema(value_type = Option<String>, example = "cbz")]
pub r#type: Option<String>,
#[schema(value_type = Option<String>, example = "cbz")]
pub kind: Option<String>,
#[schema(value_type = Option<usize>, example = 20)]
pub limit: Option<usize>,
}
#[derive(Serialize)]
#[derive(Serialize, ToSchema)]
pub struct SearchResponse {
pub hits: serde_json::Value,
pub estimated_total_hits: Option<u64>,
pub processing_time_ms: Option<u64>,
}
#[utoipa::path(
get,
path = "/search",
tag = "books",
params(
("q" = String, description = "Search query"),
("library_id" = Option<String>, Query, description = "Filter by library ID"),
("type" = Option<String>, Query, description = "Filter by type (cbz, cbr, pdf)"),
("kind" = Option<String>, Query, description = "Filter by kind (alias for type)"),
("limit" = Option<usize>, Query, description = "Max results (max 100)"),
),
responses(
(status = 200, body = SearchResponse),
)
)]
pub async fn search_books(
State(state): State<AppState>,
Query(query): Query<SearchQuery>,

72
apps/api/src/tokens.rs
View File

@@ -6,17 +6,33 @@ use rand::{rngs::OsRng, RngCore};
use serde::{Deserialize, Serialize};
use sqlx::Row;
use uuid::Uuid;
use utoipa::ToSchema;
use crate::{error::ApiError, AppState};
#[derive(Deserialize)]
pub struct CreateTokenInput {
#[derive(Deserialize, ToSchema)]
pub struct CreateTokenRequest {
#[schema(value_type = String, example = "My API Token")]
pub name: String,
#[schema(value_type = Option<String>, example = "read")]
pub scope: Option<String>,
}
#[derive(Serialize)]
pub struct CreatedToken {
#[derive(Serialize, ToSchema)]
pub struct TokenResponse {
pub id: Uuid,
pub name: String,
pub scope: String,
pub prefix: String,
#[schema(value_type = Option<String>)]
pub last_used_at: Option<DateTime<Utc>>,
#[schema(value_type = Option<String>)]
pub revoked_at: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
}
#[derive(Serialize, ToSchema)]
pub struct CreatedTokenResponse {
pub id: Uuid,
pub name: String,
pub scope: String,
@@ -24,21 +40,20 @@ pub struct CreatedToken {
pub prefix: String,
}
#[derive(Serialize)]
pub struct TokenItem {
pub id: Uuid,
pub name: String,
pub scope: String,
pub prefix: String,
pub last_used_at: Option<DateTime<Utc>>,
pub revoked_at: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
}
#[utoipa::path(
post,
path = "/admin/tokens",
tag = "admin",
request_body = CreateTokenRequest,
responses(
(status = 200, body = CreatedTokenResponse, description = "Token created - token is only shown once"),
(status = 400, description = "Invalid input"),
)
)]
pub async fn create_token(
State(state): State<AppState>,
Json(input): Json<CreateTokenInput>,
) -> Result<Json<CreatedToken>, ApiError> {
Json(input): Json<CreateTokenRequest>,
) -> Result<Json<CreatedTokenResponse>, ApiError> {
if input.name.trim().is_empty() {
return Err(ApiError::bad_request("name is required"));
}
@@ -73,7 +88,7 @@ pub async fn create_token(
.execute(&state.pool)
.await?;
Ok(Json(CreatedToken {
Ok(Json(CreatedTokenResponse {
id,
name: input.name.trim().to_string(),
scope: scope.to_string(),
@@ -82,7 +97,15 @@ pub async fn create_token(
}))
}
pub async fn list_tokens(State(state): State<AppState>) -> Result<Json<Vec<TokenItem>>, ApiError> {
#[utoipa::path(
get,
path = "/admin/tokens",
tag = "admin",
responses(
(status = 200, body = Vec<TokenResponse>),
)
)]
pub async fn list_tokens(State(state): State<AppState>) -> Result<Json<Vec<TokenResponse>>, ApiError> {
let rows = sqlx::query(
"SELECT id, name, scope, prefix, last_used_at, revoked_at, created_at FROM api_tokens ORDER BY created_at DESC",
)
@@ -91,7 +114,7 @@ pub async fn list_tokens(State(state): State<AppState>) -> Result<Json<Vec<Token
let items = rows
.into_iter()
.map(|row| TokenItem {
.map(|row| TokenResponse {
id: row.get("id"),
name: row.get("name"),
scope: row.get("scope"),
@@ -105,6 +128,15 @@ pub async fn list_tokens(State(state): State<AppState>) -> Result<Json<Vec<Token
Ok(Json(items))
}
#[utoipa::path(
delete,
path = "/admin/tokens/{id}",
tag = "admin",
responses(
(status = 200, description = "Token revoked"),
(status = 404, description = "Token not found"),
)
)]
pub async fn revoke_token(
State(state): State<AppState>,
Path(id): Path<Uuid>,