docs: add REST API documentation (#2981)

Signed-off-by: Ludovic Ortega <ludovic.ortega@adminafk.fr>
Co-authored-by: 0xsysr3ll <0xsysr3ll@pm.me>
Co-authored-by: Gauthier <mail@gauthierth.fr>

.github/workflows/docs-deploy.yml

@@ -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

.github/workflows/test-docs.yml

@@ -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

.gitignore

@@ -14,6 +14,10 @@ lcov.info
 # production
 /build
 
+# ignore REST API documentation
+docs/api/*
+!docs/api/_category_.json
+
 # misc
 .DS_Store
 *.pem

bin/duplicate-detector/package.json

@@ -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"

docs/api/_category_.json

@@ -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."
+  }
+}

docs/troubleshooting.mdx

@@ -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
 

gen-docs/README.md

@@ -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.
+

gen-docs/docusaurus.config.ts

@@ -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: {

gen-docs/package.json

@@ -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": [

gen-docs/scripts/clean-api-docs.cjs

@@ -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);