From 273d0244aa1ce97957f1cabb1abe51bc38528a98 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 23 Mar 2026 02:33:54 +0300 Subject: [PATCH] chore: generate a documentation index for REST API docs in `docs/api` Signed-off-by: NotAShelf Change-Id: Ia8426a63a50d07a6cec2b104951d58eb6a6a6964 --- docs/api.md | 47 ++++++++++++++++++++++++++++++++ docs/api/books.md | 6 ++--- docs/api/openapi.json | 63 ++++++++++++++++++++++++++++++++++++++----- docs/api/subtitles.md | 10 +++---- xtask/src/docs.rs | 39 ++++++++++++++++++++++++++- 5 files changed, 150 insertions(+), 15 deletions(-) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..dbc8c8d --- /dev/null +++ b/docs/api.md @@ -0,0 +1,47 @@ +# API Documentation + +This is the index of all generated REST API documentation for Pinakes. + +Documentation is generated from OpenAPI annotations via `cargo xtask docs` (or +`just docs`). Do not edit generated files by hand. + +## Reference + +- [openapi.json](api/openapi.json) - Full OpenAPI 3.0 specification + +## Endpoints by Tag + +- [Analytics](api/analytics.md) - Usage analytics and viewing history +- [Audit](api/audit.md) - Audit log entries +- [Auth](api/auth.md) - Authentication and session management +- [Backup](api/backup.md) - Database backup +- [Books](api/books.md) - Book metadata, series, authors, and reading progress +- [Collections](api/collections.md) - Media collections +- [Config](api/config.md) - Server configuration +- [Database](api/database.md) - Database administration +- [Duplicates](api/duplicates.md) - Duplicate media detection +- [Enrichment](api/enrichment.md) - External metadata enrichment +- [Export](api/export.md) - Media library export +- [Health](api/health.md) - Server health checks +- [Integrity](api/integrity.md) - Library integrity checks and repairs +- [Jobs](api/jobs.md) - Background job management +- [Media](api/media.md) - Media item management +- [Notes](api/notes.md) - Markdown notes link graph +- [Photos](api/photos.md) - Photo timeline and map view +- [Playlists](api/playlists.md) - Media playlists +- [Plugins](api/plugins.md) - Plugin management +- [Saved_searches](api/saved_searches.md) - Saved search queries +- [Scan](api/scan.md) - Directory scanning +- [Scheduled_tasks](api/scheduled_tasks.md) - Scheduled background tasks +- [Search](api/search.md) - Full-text media search +- [Shares](api/shares.md) - Media sharing and notifications +- [Social](api/social.md) - Ratings, comments, favorites, and share links +- [Statistics](api/statistics.md) - Library statistics +- [Streaming](api/streaming.md) - HLS and DASH adaptive streaming +- [Subtitles](api/subtitles.md) - Media subtitle management +- [Sync](api/sync.md) - Multi-device library synchronization +- [Tags](api/tags.md) - Media tag management +- [Transcode](api/transcode.md) - Video transcoding sessions +- [Upload](api/upload.md) - File upload and managed storage +- [Users](api/users.md) - User and library access management +- [Webhooks](api/webhooks.md) - Webhook configuration diff --git a/docs/api/books.md b/docs/api/books.md index 3ddf863..1ab3162 100644 --- a/docs/api/books.md +++ b/docs/api/books.md @@ -85,9 +85,9 @@ Get user's reading list #### Parameters -| Name | In | Required | Description | -| -------- | ----- | -------- | ------------------------ | -| `status` | query | No | Filter by reading status | +| Name | In | Required | Description | +| -------- | ----- | -------- | ------------------------------------------------------------------------------ | +| `status` | query | No | Filter by reading status. Valid values: to_read, reading, completed, abandoned | #### Responses diff --git a/docs/api/openapi.json b/docs/api/openapi.json index 3f86923..7e25e7c 100644 --- a/docs/api/openapi.json +++ b/docs/api/openapi.json @@ -1275,7 +1275,7 @@ { "name": "status", "in": "query", - "description": "Filter by reading status", + "description": "Filter by reading status. Valid values: to_read, reading, completed, abandoned", "required": false, "schema": { "type": "string" @@ -4704,14 +4704,11 @@ ], "responses": { "200": { - "description": "Subtitles", + "description": "Subtitles and available embedded tracks", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SubtitleResponse" - } + "$ref": "#/components/schemas/SubtitleListResponse" } } } @@ -8529,6 +8526,7 @@ "integer", "null" ], + "format": "int32", "minimum": 0 } } @@ -11787,6 +11785,28 @@ ], "description": "Response for accessing shared content.\nSingle-media shares return the media object directly (backwards compatible).\nCollection/Tag/SavedSearch shares return a list of items." }, + "SubtitleListResponse": { + "type": "object", + "description": "Response for listing subtitles on a media item.", + "required": [ + "subtitles", + "available_tracks" + ], + "properties": { + "available_tracks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubtitleTrackInfoResponse" + } + }, + "subtitles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubtitleResponse" + } + } + } + }, "SubtitleResponse": { "type": "object", "required": [ @@ -11829,10 +11849,41 @@ "integer", "null" ], + "format": "int32", "minimum": 0 } } }, + "SubtitleTrackInfoResponse": { + "type": "object", + "description": "Information about an embedded subtitle track available for extraction.", + "required": [ + "index", + "format" + ], + "properties": { + "format": { + "type": "string" + }, + "index": { + "type": "integer", + "format": "int32", + "minimum": 0 + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "title": { + "type": [ + "string", + "null" + ] + } + } + }, "SyncChangeResponse": { "type": "object", "required": [ diff --git a/docs/api/subtitles.md b/docs/api/subtitles.md index d170681..8387484 100644 --- a/docs/api/subtitles.md +++ b/docs/api/subtitles.md @@ -16,11 +16,11 @@ Media subtitle management #### Responses -| Status | Description | -| ------ | ------------ | -| 200 | Subtitles | -| 401 | Unauthorized | -| 404 | Not found | +| Status | Description | +| ------ | --------------------------------------- | +| 200 | Subtitles and available embedded tracks | +| 401 | Unauthorized | +| 404 | Not found | --- diff --git a/xtask/src/docs.rs b/xtask/src/docs.rs index 5f9872c..bcf373a 100644 --- a/xtask/src/docs.rs +++ b/xtask/src/docs.rs @@ -95,8 +95,45 @@ pub fn run() { files_written += 1; } + // Generate docs/api.md index + let index_path = std::path::Path::new("docs/api.md"); + let mut index = String::new(); + index.push_str("# API Documentation\n\n"); + index.push_str( + "This is the index of all generated REST API documentation for \ + Pinakes.\n\n", + ); + index.push_str( + "Documentation is generated from OpenAPI annotations via `cargo xtask \ + docs`\n", + ); + index.push_str("(or `just docs`). Do not edit generated files by hand.\n\n"); + index.push_str("## Reference\n\n"); + index.push_str( + "- [openapi.json](api/openapi.json) - Full OpenAPI 3.0 specification\n\n", + ); + index.push_str("## Endpoints by Tag\n\n"); + for tag_name in tag_ops.keys() { + let file_name = format!("{}.md", tag_name.replace('/', "_")); + let description = tag_descriptions.get(tag_name).map_or("", String::as_str); + if description.is_empty() { + writeln!(index, "- [{}](api/{file_name})", title_case(tag_name)) + .expect("write to String"); + } else { + writeln!( + index, + "- [{}](api/{file_name}) - {description}", + title_case(tag_name) + ) + .expect("write to String"); + } + } + std::fs::write(index_path, &index).expect("write docs/api.md"); + println!("Written docs/api.md"); + println!( - "Done: wrote docs/api/openapi.json and {files_written} markdown files." + "Done: wrote docs/api/openapi.json, docs/api.md, and {files_written} \ + markdown files." ); }