chore: generate a documentation index for REST API docs in docs/api

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: Ia8426a63a50d07a6cec2b104951d58eb6a6a6964

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

docs/api/books.md

@@ -85,9 +85,9 @@ Get user's reading list
 
 #### Parameters
 
-| Name     | In    | Required | Description              |
+| Name     | In    | Required | Description                                                                    |
-| -------- | ----- | -------- | ------------------------ |
+| -------- | ----- | -------- | ------------------------------------------------------------------------------ |
-| `status` | query | No       | Filter by reading status |
+| `status` | query | No       | Filter by reading status. Valid values: to_read, reading, completed, abandoned |
 
 #### Responses
 

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",
+                  "$ref": "#/components/schemas/SubtitleListResponse"
-                  "items": {
-                    "$ref": "#/components/schemas/SubtitleResponse"
-                  }
                 }
               }
             }
@@ -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": [

docs/api/subtitles.md

@@ -16,11 +16,11 @@ Media subtitle management
 
 #### Responses
 
-| Status | Description  |
+| Status | Description                             |
-| ------ | ------------ |
+| ------ | --------------------------------------- |
-| 200    | Subtitles    |
+| 200    | Subtitles and available embedded tracks |
-| 401    | Unauthorized |
+| 401    | Unauthorized                            |
-| 404    | Not found    |
+| 404    | Not found                               |
 
 ---
 

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."
   );
 }