feat(server): serve normalized OpenAPI spec at /api/v1/spec.json with shared schema components

Extract spec generation into `openapi-spec.ts` with a `generateOpenApiSpec` function that registers common `$ref` schemas (Title, Person, Episode, Season, etc.) to deduplicate inline definitions across the spec. Add a `/api/v1/spec.json` interceptor that returns the fully normalized document, and point the Scalar docs UI at it instead of the plugin's raw generator output.

Also strip oRPC's impossible `{ not: {} }` void placeholders from request/response bodies via `normalizeOpenApiSpec`, and fix the handler registration so both `/api/v1` and `/api/v1/*` routes are matched.
This commit is contained in:
2026-03-14 20:05:44 -04:00
parent aede4fc90a
commit 33fd871114
20 changed files with 5153 additions and 2928 deletions
+17 -9
View File
@@ -5,23 +5,31 @@ full: true
_openapi:
toc:
- depth: 2
title: Update Name
url: '#update-name'
title: Update display name
url: '#update-display-name'
- depth: 2
title: Upload Avatar
title: Upload avatar
url: '#upload-avatar'
- depth: 2
title: Remove Avatar
title: Remove avatar
url: '#remove-avatar'
structuredData:
headings:
- content: Update Name
id: update-name
- content: Upload Avatar
- content: Update display name
id: update-display-name
- content: Upload avatar
id: upload-avatar
- content: Remove Avatar
- content: Remove avatar
id: remove-avatar
contents: []
contents:
- content: Change the current user's display name.
heading: update-display-name
- content: >-
Upload a new profile avatar image. Accepts JPEG, PNG, WebP, or GIF up
to 2 MB.
heading: upload-avatar
- content: Delete the current user's profile avatar, reverting to the default.
heading: remove-avatar
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+87 -49
View File
@@ -5,73 +5,111 @@ full: true
_openapi:
toc:
- depth: 2
title: List
url: '#list'
title: List backups
url: '#list-backups'
- depth: 2
title: Create
url: '#create'
title: Create backup
url: '#create-backup'
- depth: 2
title: Delete
url: '#delete'
title: Delete backup
url: '#delete-backup'
- depth: 2
title: Restore
url: '#restore'
title: Restore from backup
url: '#restore-from-backup'
- depth: 2
title: Schedule
url: '#schedule'
title: Get backup schedule
url: '#get-backup-schedule'
- depth: 2
title: Update Schedule
url: '#update-schedule'
title: Update backup schedule
url: '#update-backup-schedule'
- depth: 2
title: Registration
url: '#registration'
title: Get registration status
url: '#get-registration-status'
- depth: 2
title: Toggle Registration
title: Toggle registration
url: '#toggle-registration'
- depth: 2
title: Update Check
url: '#update-check'
title: Get update check status
url: '#get-update-check-status'
- depth: 2
title: Toggle Update Check
url: '#toggle-update-check'
title: Toggle update checks
url: '#toggle-update-checks'
- depth: 2
title: Telemetry
url: '#telemetry'
title: Get telemetry status
url: '#get-telemetry-status'
- depth: 2
title: Toggle Telemetry
title: Toggle telemetry
url: '#toggle-telemetry'
- depth: 2
title: Trigger Job
url: '#trigger-job'
title: Trigger cron job
url: '#trigger-cron-job'
structuredData:
headings:
- content: List
id: list
- content: Create
id: create
- content: Delete
id: delete
- content: Restore
id: restore
- content: Schedule
id: schedule
- content: Update Schedule
id: update-schedule
- content: Registration
id: registration
- content: Toggle Registration
- content: List backups
id: list-backups
- content: Create backup
id: create-backup
- content: Delete backup
id: delete-backup
- content: Restore from backup
id: restore-from-backup
- content: Get backup schedule
id: get-backup-schedule
- content: Update backup schedule
id: update-backup-schedule
- content: Get registration status
id: get-registration-status
- content: Toggle registration
id: toggle-registration
- content: Update Check
id: update-check
- content: Toggle Update Check
id: toggle-update-check
- content: Telemetry
id: telemetry
- content: Toggle Telemetry
- content: Get update check status
id: get-update-check-status
- content: Toggle update checks
id: toggle-update-checks
- content: Get telemetry status
id: get-telemetry-status
- content: Toggle telemetry
id: toggle-telemetry
- content: Trigger Job
id: trigger-job
contents: []
- content: Trigger cron job
id: trigger-cron-job
contents:
- content: Fetch all database backups with their sizes and creation times.
heading: list-backups
- content: >-
Create a new manual database backup. The backup is tagged as a manual
backup.
heading: create-backup
- content: Permanently delete a database backup file by filename.
heading: delete-backup
- content: >-
Upload a database backup file and restore it. A pre-restore backup is
automatically created before overwriting the current database.
heading: restore-from-backup
- content: Fetch the current automated backup schedule configuration.
heading: get-backup-schedule
- content: >-
Update the automated backup schedule. Only provided fields are
changed; omitted fields keep their current values.
heading: update-backup-schedule
- content: Check whether new user registration is currently open or closed.
heading: get-registration-status
- content: Open or close new user registration.
heading: toggle-registration
- content: >-
Fetch whether automatic update checks are enabled, and the latest
cached check result if available.
heading: get-update-check-status
- content: Enable or disable automatic update checks against the public API.
heading: toggle-update-checks
- content: >-
Fetch whether anonymous telemetry is enabled and when the last report
was sent.
heading: get-telemetry-status
- content: Enable or disable anonymous telemetry reporting.
heading: toggle-telemetry
- content: >-
Manually trigger a background cron job by name. The job runs
asynchronously.
heading: trigger-cron-job
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+39 -21
View File
@@ -5,33 +5,51 @@ full: true
_openapi:
toc:
- depth: 2
title: Stats
url: '#stats'
title: Get dashboard statistics
url: '#get-dashboard-statistics'
- depth: 2
title: Continue Watching
url: '#continue-watching'
title: Get continue watching list
url: '#get-continue-watching-list'
- depth: 2
title: Library
url: '#library'
title: Get user library
url: '#get-user-library'
- depth: 2
title: Recommendations
url: '#recommendations'
title: Get personalized recommendations
url: '#get-personalized-recommendations'
- depth: 2
title: Watch History
url: '#watch-history'
title: Get watch history
url: '#get-watch-history'
structuredData:
headings:
- content: Stats
id: stats
- content: Continue Watching
id: continue-watching
- content: Library
id: library
- content: Recommendations
id: recommendations
- content: Watch History
id: watch-history
contents: []
- content: Get dashboard statistics
id: get-dashboard-statistics
- content: Get continue watching list
id: get-continue-watching-list
- content: Get user library
id: get-user-library
- content: Get personalized recommendations
id: get-personalized-recommendations
- content: Get watch history
id: get-watch-history
contents:
- content: >-
Fetch summary counts for the current user: movies watched this month,
episodes this week, library size, and completed titles.
heading: get-dashboard-statistics
- content: >-
Fetch TV shows the user is currently watching, with the next unwatched
episode and progress for each.
heading: get-continue-watching-list
- content: Fetch all titles in the user's library with their tracking statuses.
heading: get-user-library
- content: >-
Fetch personalized title recommendations based on the user's library
and watch history.
heading: get-personalized-recommendations
- content: >-
Fetch the user's watch counts grouped by time period. Useful for
rendering activity charts.
heading: get-watch-history
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+9 -5
View File
@@ -6,13 +6,17 @@ _openapi:
method: GET
toc:
- depth: 2
title: Discover
url: '#discover'
title: Discover titles by genre
url: '#discover-titles-by-genre'
structuredData:
headings:
- content: Discover
id: discover
contents: []
- content: Discover titles by genre
id: discover-titles-by-genre
contents:
- content: >-
Browse movies or TV shows filtered by genre, sorted by popularity.
Returns user statuses and episode progress.
heading: discover-titles-by-genre
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+21 -13
View File
@@ -5,23 +5,31 @@ full: true
_openapi:
toc:
- depth: 2
title: Watch
url: '#watch'
title: Mark episode watched
url: '#mark-episode-watched'
- depth: 2
title: Unwatch
url: '#unwatch'
title: Mark episode unwatched
url: '#mark-episode-unwatched'
- depth: 2
title: Batch Watch
url: '#batch-watch'
title: Batch mark episodes watched
url: '#batch-mark-episodes-watched'
structuredData:
headings:
- content: Watch
id: watch
- content: Unwatch
id: unwatch
- content: Batch Watch
id: batch-watch
contents: []
- content: Mark episode watched
id: mark-episode-watched
- content: Mark episode unwatched
id: mark-episode-unwatched
- content: Batch mark episodes watched
id: batch-mark-episodes-watched
contents:
- content: Record a watch event for a single TV episode.
heading: mark-episode-watched
- content: Remove the watch record for a single TV episode.
heading: mark-episode-unwatched
- content: >-
Record watch events for multiple episodes at once. Useful for marking
a range of episodes as watched.
heading: batch-mark-episodes-watched
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+25 -13
View File
@@ -5,23 +5,35 @@ full: true
_openapi:
toc:
- depth: 2
title: Trending
url: '#trending'
title: Get trending titles
url: '#get-trending-titles'
- depth: 2
title: Popular
url: '#popular'
title: Get popular titles
url: '#get-popular-titles'
- depth: 2
title: Genres
url: '#genres'
title: List genres
url: '#list-genres'
structuredData:
headings:
- content: Trending
id: trending
- content: Popular
id: popular
- content: Genres
id: genres
contents: []
- content: Get trending titles
id: get-trending-titles
- content: Get popular titles
id: get-popular-titles
- content: List genres
id: list-genres
contents:
- content: >-
Fetch today's trending movies and/or TV shows from TMDB, including a
featured hero title and the user's statuses.
heading: get-trending-titles
- content: >-
Fetch currently popular movies or TV shows from TMDB with the user's
tracking statuses.
heading: get-popular-titles
- content: >-
Fetch the list of TMDB genres for movies or TV shows. Used to populate
genre filters for discovery.
heading: list-genres
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+31 -17
View File
@@ -5,28 +5,42 @@ full: true
_openapi:
toc:
- depth: 2
title: List
url: '#list'
title: List integrations
url: '#list-integrations'
- depth: 2
title: Create
url: '#create'
title: Create or update integration
url: '#create-or-update-integration'
- depth: 2
title: Delete
url: '#delete'
title: Delete integration
url: '#delete-integration'
- depth: 2
title: Regenerate Token
url: '#regenerate-token'
title: Regenerate webhook token
url: '#regenerate-webhook-token'
structuredData:
headings:
- content: List
id: list
- content: Create
id: create
- content: Delete
id: delete
- content: Regenerate Token
id: regenerate-token
contents: []
- content: List integrations
id: list-integrations
- content: Create or update integration
id: create-or-update-integration
- content: Delete integration
id: delete-integration
- content: Regenerate webhook token
id: regenerate-webhook-token
contents:
- content: >-
Fetch all configured media server integrations for the current user,
including recent webhook/sync events for each.
heading: list-integrations
- content: >-
Create a new media server integration or update an existing one.
Generates a unique webhook token for the provider.
heading: create-or-update-integration
- content: Remove a media server integration and all its event history.
heading: delete-integration
- content: >-
Generate a new webhook token for an integration. The old token is
immediately invalidated.
heading: regenerate-webhook-token
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+17 -9
View File
@@ -5,18 +5,26 @@ full: true
_openapi:
toc:
- depth: 2
title: Detail
url: '#detail'
title: Get person details
url: '#get-person-details'
- depth: 2
title: Resolve
url: '#resolve'
title: Resolve TMDB ID to local person
url: '#resolve-tmdb-id-to-local-person'
structuredData:
headings:
- content: Detail
id: detail
- content: Resolve
id: resolve
contents: []
- content: Get person details
id: get-person-details
- content: Resolve TMDB ID to local person
id: resolve-tmdb-id-to-local-person
contents:
- content: >-
Fetch a person's profile and filmography. Imports from TMDB on first
access if not yet cached locally.
heading: get-person-details
- content: >-
Look up or import a person by their TMDB ID. Returns the internal ID
for use with other endpoints.
heading: resolve-tmdb-id-to-local-person
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+9 -5
View File
@@ -6,13 +6,17 @@ _openapi:
method: GET
toc:
- depth: 2
title: Search
url: '#search'
title: Search movies, TV shows, and people
url: '#search-movies-tv-shows-and-people'
structuredData:
headings:
- content: Search
id: search
contents: []
- content: Search movies, TV shows, and people
id: search-movies-tv-shows-and-people
contents:
- content: >-
Full-text search across movies, TV shows, and people via TMDB.
Optionally filter by media type.
heading: search-movies-tv-shows-and-people
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+15 -9
View File
@@ -5,18 +5,24 @@ full: true
_openapi:
toc:
- depth: 2
title: Watch
url: '#watch'
title: Mark season watched
url: '#mark-season-watched'
- depth: 2
title: Unwatch
url: '#unwatch'
title: Mark season unwatched
url: '#mark-season-unwatched'
structuredData:
headings:
- content: Watch
id: watch
- content: Unwatch
id: unwatch
contents: []
- content: Mark season watched
id: mark-season-watched
- content: Mark season unwatched
id: mark-season-unwatched
contents:
- content: Mark all episodes in a season as watched in a single operation.
heading: mark-season-watched
- content: >-
Remove all watch records for episodes in a season in a single
operation.
heading: mark-season-unwatched
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+35 -17
View File
@@ -5,28 +5,46 @@ full: true
_openapi:
toc:
- depth: 2
title: Public Info
url: '#public-info'
title: Get public instance info
url: '#get-public-instance-info'
- depth: 2
title: Auth Config
url: '#auth-config'
title: Get authentication config
url: '#get-authentication-config'
- depth: 2
title: Status
url: '#status'
title: Get system status
url: '#get-system-status'
- depth: 2
title: Health
url: '#health'
title: Get system health report
url: '#get-system-health-report'
structuredData:
headings:
- content: Public Info
id: public-info
- content: Auth Config
id: auth-config
- content: Status
id: status
- content: Health
id: health
contents: []
- content: Get public instance info
id: get-public-instance-info
- content: Get authentication config
id: get-authentication-config
- content: Get system status
id: get-system-status
- content: Get system health report
id: get-system-health-report
contents:
- content: >-
Fetch public information about this Sofa instance. Does not require
authentication. Used by the login screen to display instance details.
heading: get-public-instance-info
- content: >-
Fetch the authentication configuration including OIDC availability,
password login status, and registration state. Does not require
authentication.
heading: get-authentication-config
- content: >-
Quick check of whether TMDB is configured. Does not require
authentication.
heading: get-system-status
- content: >-
Comprehensive health check covering database, TMDB connectivity, cron
jobs, image cache, backups, and environment. Does not require
authentication.
heading: get-system-health-report
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+79 -41
View File
@@ -5,58 +5,96 @@ full: true
_openapi:
toc:
- depth: 2
title: Detail
url: '#detail'
title: Get title details
url: '#get-title-details'
- depth: 2
title: Resolve
url: '#resolve'
title: Resolve TMDB ID to local title
url: '#resolve-tmdb-id-to-local-title'
- depth: 2
title: Update Status
url: '#update-status'
title: Update tracking status
url: '#update-tracking-status'
- depth: 2
title: Update Rating
url: '#update-rating'
title: Rate a title
url: '#rate-a-title'
- depth: 2
title: Watch Movie
url: '#watch-movie'
title: Mark movie as watched
url: '#mark-movie-as-watched'
- depth: 2
title: Watch All
url: '#watch-all'
title: Mark all episodes watched
url: '#mark-all-episodes-watched'
- depth: 2
title: User Info
url: '#user-info'
title: Get user's title info
url: '#get-users-title-info'
- depth: 2
title: Recommendations
url: '#recommendations'
title: Get title recommendations
url: '#get-title-recommendations'
- depth: 2
title: Hydrate Seasons
url: '#hydrate-seasons'
title: Hydrate TV seasons
url: '#hydrate-tv-seasons'
- depth: 2
title: Quick Add
url: '#quick-add'
title: Quick add title to library
url: '#quick-add-title-to-library'
structuredData:
headings:
- content: Detail
id: detail
- content: Resolve
id: resolve
- content: Update Status
id: update-status
- content: Update Rating
id: update-rating
- content: Watch Movie
id: watch-movie
- content: Watch All
id: watch-all
- content: User Info
id: user-info
- content: Recommendations
id: recommendations
- content: Hydrate Seasons
id: hydrate-seasons
- content: Quick Add
id: quick-add
contents: []
- content: Get title details
id: get-title-details
- content: Resolve TMDB ID to local title
id: resolve-tmdb-id-to-local-title
- content: Update tracking status
id: update-tracking-status
- content: Rate a title
id: rate-a-title
- content: Mark movie as watched
id: mark-movie-as-watched
- content: Mark all episodes watched
id: mark-all-episodes-watched
- content: Get user's title info
id: get-users-title-info
- content: Get title recommendations
id: get-title-recommendations
- content: Hydrate TV seasons
id: hydrate-tv-seasons
- content: Quick add title to library
id: quick-add-title-to-library
contents:
- content: >-
Fetch full title metadata including seasons, cast, and streaming
availability. Imports from TMDB on first access if not yet cached
locally.
heading: get-title-details
- content: >-
Look up or import a title by its TMDB ID and media type. Returns the
internal ID for use with other endpoints.
heading: resolve-tmdb-id-to-local-title
- content: >-
Set the user's tracking status for a title. Use null to remove the
title from the library entirely.
heading: update-tracking-status
- content: Set a 0-5 star rating for a title. Use 0 to clear the rating.
heading: rate-a-title
- content: Log a watch event for a movie. Automatically sets status to completed.
heading: mark-movie-as-watched
- content: >-
Mark every episode of a TV show as watched. Requires seasons to be
hydrated first.
heading: mark-all-episodes-watched
- content: >-
Fetch the current user's tracking status, rating, and watched episode
IDs for a title.
heading: get-users-title-info
- content: >-
Fetch similar titles based on locally cached recommendation data,
along with the user's statuses for each.
heading: get-title-recommendations
- content: >-
Fetch full season and episode data from TMDB for a TV show. Required
before tracking individual episodes.
heading: hydrate-tv-seasons
- content: >-
Import a title by TMDB ID and add it to the user's watchlist in one
step. If the title already exists in the user's library, returns
alreadyAdded: true.
heading: quick-add-title-to-library
---
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+3163 -2182
View File
File diff suppressed because it is too large Load Diff