From 9cf671ac94f17e4269154ef245c8d8ea74addb20 Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <shu@vanwa.ch>
Date: Wed, 2 Jul 2025 22:06:16 +0200
Subject: [PATCH] openapi docs

---
 little-hesinde/src/api/html/authors.rs | 3 +++
 little-hesinde/src/api/html/books.rs   | 3 +++
 little-hesinde/src/api/html/cover.rs   | 2 ++
 little-hesinde/src/api/html/search.rs  | 1 +
 little-hesinde/src/api/html/series.rs  | 3 +++
 little-hesinde/src/api/opds/recent.rs  | 1 +
 little-hesinde/src/api/opds/search.rs  | 1 +
 little-hesinde/src/api/static_files.rs | 1 +
 8 files changed, 15 insertions(+)

diff --git a/little-hesinde/src/api/html/authors.rs b/little-hesinde/src/api/html/authors.rs
index 604f79c..c7c2a97 100644
--- a/little-hesinde/src/api/html/authors.rs
+++ b/little-hesinde/src/api/html/authors.rs
@@ -36,6 +36,7 @@ impl HttpStatus for RetrieveError {
 }
 http_error!(RetrieveError);
 
+/// Get the first page of all authors.
 #[utoipa::path(
     get,
     path = "/authors",
@@ -51,6 +52,7 @@ pub async fn handler_init(State(state): State<Arc<AppState>>) -> Result<Response
         .context(AuthorsSnafu)
 }
 
+/// Get a paginated list of all authors.
 #[utoipa::path(
     get,
     path = "/authors/{cursor}/{sort_order}",
@@ -113,6 +115,7 @@ impl HttpStatus for SingleError {
 }
 http_error!(SingleError);
 
+/// Get a single author and all their books.
 #[utoipa::path(
     get,
     path = "/authors/{id}",
diff --git a/little-hesinde/src/api/html/books.rs b/little-hesinde/src/api/html/books.rs
index 22c9177..d23fdac 100644
--- a/little-hesinde/src/api/html/books.rs
+++ b/little-hesinde/src/api/html/books.rs
@@ -38,6 +38,7 @@ impl HttpStatus for RetrieveError {
 }
 http_error!(RetrieveError);
 
+/// Get the first page of all books.
 #[utoipa::path(
     get,
     path = "/books",
@@ -53,6 +54,7 @@ pub async fn handler_init(State(state): State<Arc<AppState>>) -> Result<Response
         .context(BooksSnafu)
 }
 
+/// Get a paginated list of all books.
 #[utoipa::path(
     get,
     path = "/books/{cursor}/{sort_order}",
@@ -134,6 +136,7 @@ impl HttpStatus for DownloadError {
 }
 http_error!(DownloadError);
 
+/// Download a book file in the specified format.
 #[utoipa::path(
     get,
     path = "/book/{id}/{format}",
diff --git a/little-hesinde/src/api/html/cover.rs b/little-hesinde/src/api/html/cover.rs
index 702c07d..b029e35 100644
--- a/little-hesinde/src/api/html/cover.rs
+++ b/little-hesinde/src/api/html/cover.rs
@@ -41,6 +41,7 @@ impl HttpStatus for RetrieveError {
 }
 http_error!(RetrieveError);
 
+/// Get the thumbnail for a book cover.
 #[utoipa::path(
     get,
     path = "/cover/{id}/thumbnail",
@@ -67,6 +68,7 @@ pub async fn thumbnail(
     .context(CoverSnafu)
 }
 
+/// Get the full-size cover for a book.
 #[utoipa::path(
     get,
     path = "/cover/{id}",
diff --git a/little-hesinde/src/api/html/search.rs b/little-hesinde/src/api/html/search.rs
index 353336d..105e49f 100644
--- a/little-hesinde/src/api/html/search.rs
+++ b/little-hesinde/src/api/html/search.rs
@@ -44,6 +44,7 @@ pub struct Params {
     /// Query for a search request.
     query: String,
 }
+/// Search for books based on a query.
 #[utoipa::path(
     get,
     path = "/search",
diff --git a/little-hesinde/src/api/html/series.rs b/little-hesinde/src/api/html/series.rs
index fb87fd4..2287b2c 100644
--- a/little-hesinde/src/api/html/series.rs
+++ b/little-hesinde/src/api/html/series.rs
@@ -36,6 +36,7 @@ impl HttpStatus for RetrieveError {
 }
 http_error!(RetrieveError);
 
+/// Get the first page of all series.
 #[utoipa::path(
     get,
     path = "/series",
@@ -51,6 +52,7 @@ pub async fn handler_init(State(state): State<Arc<AppState>>) -> Result<Response
         .context(SeriesSnafu)
 }
 
+/// Get a paginated list of all series.
 #[utoipa::path(
     get,
     path = "/series/{cursor}/{sort_order}",
@@ -113,6 +115,7 @@ impl HttpStatus for SingleError {
 }
 http_error!(SingleError);
 
+/// Get a single series and all its books.
 #[utoipa::path(
     get,
     path = "/series/{id}",
diff --git a/little-hesinde/src/api/opds/recent.rs b/little-hesinde/src/api/opds/recent.rs
index f727fbe..eebdb83 100644
--- a/little-hesinde/src/api/opds/recent.rs
+++ b/little-hesinde/src/api/opds/recent.rs
@@ -43,6 +43,7 @@ impl HttpStatus for RecentError {
 }
 http_error!(RecentError);
 
+/// Get recently added books as an OPDS feed.
 #[utoipa::path(
     get,
     path = "/recent",
diff --git a/little-hesinde/src/api/opds/search.rs b/little-hesinde/src/api/opds/search.rs
index fa55e08..3260640 100644
--- a/little-hesinde/src/api/opds/search.rs
+++ b/little-hesinde/src/api/opds/search.rs
@@ -50,6 +50,7 @@ pub struct Params {
     /// Query for a search request.
     query: String,
 }
+/// Search for books and return results as an OPDS feed.
 #[utoipa::path(
     get,
     path = "/search",
diff --git a/little-hesinde/src/api/static_files.rs b/little-hesinde/src/api/static_files.rs
index 9c8d877..c6f1ff6 100644
--- a/little-hesinde/src/api/static_files.rs
+++ b/little-hesinde/src/api/static_files.rs
@@ -10,6 +10,7 @@ use rust_embed::RustEmbed;
 pub struct Files;
 
 /// Get static file from the 'static' folder.
+/// Serve a static file.
 #[utoipa::path(
     get,
     path = "/static/{*file}",