docs: add REST API documentation (#2981)

Signed-off-by: Ludovic Ortega <[email protected]> Co-authored-by: 0xsysr3ll <[email protected]> Co-authored-by: Gauthier <[email protected]>
2026-10-12 02:22:17 +00:00 · 2026-05-13 13:27:56 +02:00
parent cf8720515c
commit 7aa1470ce6
11 changed files with 1746 additions and 474 deletions
@@ -10,6 +10,7 @@ on:
    paths:
      - 'docs/**'
      - 'gen-docs/**'
+      - 'seerr-api.yml'

 permissions:
  contents: read
@@ -57,7 +58,7 @@ jobs:

      - name: Build website
        working-directory: gen-docs
-        run: pnpm build
+        run: pnpm gen-api-docs all && pnpm build

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b6 # v4.0.0
@@ -1,6 +1,6 @@
 ---
 # yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
-name: Test Docs deployment
+name: Test Docs

 on:
  pull_request:
@@ -18,8 +18,8 @@ concurrency:
  cancel-in-progress: true

 jobs:
-  test-deploy:
-    name: Test deployment
+  test-build:
+    name: Test build
    runs-on: ubuntu-24.04
    permissions:
      contents: read
@@ -14,6 +14,10 @@ lcov.info
 # production
 /build

+# ignore REST API documentation
+docs/api/*
+!docs/api/_category_.json
+
 # misc
 .DS_Store
 *.pem
@@ -3,7 +3,7 @@
  "version": "1.0.0",
  "private": true,
  "type": "module",
-  "packageManager": "pnpm@10.17.1",
+  "packageManager": "pnpm@10.24.0",
  "scripts": {
    "build-index": "node build-index.mjs",
    "detect": "node detect.mjs"
@@ -0,0 +1,9 @@
+{
+  "label": "REST API documentation",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "title": "REST API documentation",
+    "description": "Create integrations with the Seerr REST API."
+  }
+}
@@ -103,7 +103,7 @@ If you can't change your DNS servers or force IPV4 resolution, you can use Seerr

 In some places (like China), the ISP blocks not only the DNS resolution but also the connection to the TMDB API.

-You can configure Seerr to use a proxy with the [HTTP(S) Proxy](/using-seerr/settings/general#enable-proxy-support) setting.
+You can configure Seerr to use a proxy with the [HTTP(S) Proxy](/using-seerr/settings/network#enable-proxy-support) setting.

 ### Option 3: Force IPV4 resolution first

@@ -6,22 +6,39 @@ Seerr docs will be available at [docs.seerr.dev](https://docs.seerr.dev).

 ### Installation

-```
-$ pnpm install
+```bash
+pnpm install
 ```

 ### Local Development

-```
-$ pnpm start
+```bash
+pnpm start
 ```

 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

 ### Build

-```
-$ pnpm build
+```bash
+pnpm build
 ```

-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+This command generates static content in the `build` directory, which can then be served using any static content hosting service.
+
+### Test API Rest documentation
+
+This command generates REST API documentation.
+
+```bash
+pnpm gen-api-docs all
+```
+
+This command cleans REST API documentation.
+
+```bash
+pnpm clean-api-docs all
+```
+
+See [docusaurus-openapi-docs](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/tree/main#cli-usage) for more information.
+
@@ -1,5 +1,6 @@
 import type * as Preset from '@docusaurus/preset-classic';
 import type { Config } from '@docusaurus/types';
+import type * as OpenApiPlugin from 'docusaurus-plugin-openapi-docs';
 import { themes as prismThemes } from 'prism-react-renderer';

 const config: Config = {
@@ -37,6 +38,7 @@ const config: Config = {
          routeBasePath: '/',
          path: '../docs',
          editUrl: 'https://github.com/seerr-team/seerr/edit/develop/docs/',
+          docItemComponent: '@theme/ApiItem',
        },
        pages: false,
        theme: {
@@ -46,6 +48,28 @@ const config: Config = {
    ],
  ],

+  plugins: [
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: 'api',
+        docsPluginId: 'classic',
+        config: {
+          seerr: {
+            specPath: '../seerr-api.yml',
+            outputDir: '../docs/api',
+            sidebarOptions: {
+              groupPathsBy: 'tag',
+            },
+            downloadUrl:
+              'https://raw.githubusercontent.com/seerr-team/seerr/refs/heads/develop/seerr-api.yml',
+            hideSendButton: true,
+          } satisfies OpenApiPlugin.Options,
+        },
+      },
+    ],
+  ],
+
  themes: [
    [
      '@easyops-cn/docusaurus-search-local',
@@ -58,6 +82,7 @@ const config: Config = {
        explicitSearchResultPath: true,
      },
    ],
+    'docusaurus-theme-openapi-docs',
  ],

  themeConfig: {
@@ -2,11 +2,13 @@
  "name": "gen-docs",
  "version": "0.0.0",
  "private": true,
-  "packageManager": "pnpm@10.17.1",
+  "packageManager": "pnpm@10.24.0",
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
+    "gen-api-docs": "docusaurus gen-api-docs",
+    "clean-api-docs": "node ./scripts/clean-api-docs.cjs",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
@@ -16,21 +18,23 @@
    "typecheck": "tsc"
  },
  "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/preset-classic": "3.9.1",
-    "@easyops-cn/docusaurus-search-local": "^0.52.1",
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/preset-classic": "3.10.1",
+    "@easyops-cn/docusaurus-search-local": "^0.55.1",
    "@mdx-js/react": "^3.0.0",
-    "clsx": "^2.0.0",
-    "prism-react-renderer": "^2.3.0",
+    "clsx": "^2.1.1",
+    "docusaurus-plugin-openapi-docs": "^5.0.1",
+    "docusaurus-theme-openapi-docs": "^5.0.1",
+    "prism-react-renderer": "^2.4.1",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
-    "tailwindcss": "^3.4.4"
+    "tailwindcss": "^3.4.19"
  },
  "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.1",
-    "@docusaurus/tsconfig": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "typescript": "~5.2.2"
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/tsconfig": "3.10.1",
+    "@docusaurus/types": "3.10.1",
+    "typescript": "~6.0.3"
  },
  "browserslist": {
    "production": [
@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const { mkdirSync, readFileSync, writeFileSync } = require('node:fs');
+const { dirname, resolve } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const args = process.argv.slice(2);
+const categoryPath = resolve(__dirname, '../../docs/api/_category_.json');
+let categoryContent;
+
+try {
+  categoryContent = readFileSync(categoryPath, 'utf8');
+} catch {
+  categoryContent = undefined;
+}
+
+const result = spawnSync('docusaurus', ['clean-api-docs', ...args], {
+  stdio: 'inherit',
+  shell: process.platform === 'win32',
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+if (categoryContent !== undefined) {
+  mkdirSync(dirname(categoryPath), { recursive: true });
+  writeFileSync(categoryPath, categoryContent, 'utf8');
+}
+
+process.exit(result.status ?? 1);