Gandalf/sofarr
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases 23 Wiki Activity

docs(swagger): add JSDoc @openapi for proxy routes

Browse Source 
- Sonarr: queue, history, series, notifications CRUD, webhook setup
- Radarr: queue, history, movies, notifications CRUD, webhook setup
- SABnzbd: queue, history
- Emby: sessions, users
- Document that these are authenticated proxies to upstream services
- Include notification proxy endpoints for webhook configuration
This commit is contained in:
Gronod
2026-05-21 12:37:36 +01:00
parent 5c0ad7cb1b
commit 43f5a52749
4 changed files with 272 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/routes/emby.js
+67 -15
View File
@@ -5,9 +5,26 @@ const router = express.Router();
const requireAuth = require('../middleware/requireAuth');
const sanitizeError = require('../utils/sanitizeError');
/**
* @openapi
* /api/emby/sessions:
* get:
* tags: [Emby]
* summary: Get active Emby sessions
* description: Proxy to Emby's sessions endpoint. Requires authentication.
* security:
* - CookieAuth: []
* responses:
* '200':
* description: Sessions data from Emby
* content:
* application/json:
* schema:
* type: array
*/
router.use(requireAuth);
// Get active sessions
// GET /api/emby/sessions - list active Emby sessions
router.get('/sessions', async (req, res) => {
try {
const response = await axios.get(`${process.env.EMBY_URL}/Sessions`, {
@@ -19,19 +36,24 @@ router.get('/sessions', async (req, res) => {
}
});
// Get user by ID
router.get('/users/:id', async (req, res) => {
try {
const response = await axios.get(`${process.env.EMBY_URL}/Users/${req.params.id}`, {
headers: { 'X-MediaBrowser-Token': process.env.EMBY_API_KEY }
});
res.json(response.data);
} catch (error) {
res.status(500).json({ error: 'Failed to fetch user details', details: sanitizeError(error) });
}
});
// Get all users
/**
* @openapi
* /api/emby/users:
* get:
* tags: [Emby]
* summary: Get all Emby users
* description: Proxy to Emby's users list endpoint. Requires authentication.
* security:
* - CookieAuth: []
* responses:
* '200':
* description: Users list from Emby
* content:
* application/json:
* schema:
* type: array
*/
// GET /api/emby/users - list all users
router.get('/users', async (req, res) => {
try {
const response = await axios.get(`${process.env.EMBY_URL}/Users`, {
@@ -43,7 +65,37 @@ router.get('/users', async (req, res) => {
}
});
// Get current user by session ID
/**
* @openapi
* /api/emby/session/{sessionId}/user:
* get:
* tags: [Emby]
* summary: Get user from session
* description: Get user details for a specific session ID. Requires authentication.
* security:
* - CookieAuth: []
* parameters:
* - name: sessionId
* in: path
* required: true
* schema:
* type: string
* description: Emby session ID
* responses:
* '200':
* description: User data from Emby
* content:
* application/json:
* schema:
* type: object
* '404':
* description: Session not found
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
// GET /api/emby/session/:sessionId/user - get user for a specific session
router.get('/session/:sessionId/user', async (req, res) => {
try {
const response = await axios.get(`${process.env.EMBY_URL}/Sessions`, {
server/routes/radarr.js
+78
View File
@@ -15,6 +15,30 @@ function getFirstRadarrInstance() {
return instances[0];
}
/**
* @openapi
* /api/radarr/queue:
* get:
* tags: [Radarr]
* summary: Get Radarr queue
* description: Proxy to Radarr's queue endpoint. Requires authentication and CSRF token.
* security:
* - CookieAuth: []
* - CsrfToken: []
* responses:
* '200':
* description: Queue data from Radarr
* content:
* application/json:
* schema:
* type: object
* '500':
* description: Proxy error
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
router.use(requireAuth);
// Get queue
@@ -29,6 +53,30 @@ router.get('/queue', async (req, res) => {
}
});
/**
* @openapi
* /api/radarr/history:
* get:
* tags: [Radarr]
* summary: Get Radarr history
* description: Proxy to Radarr's history endpoint. Requires authentication.
* security:
* - CookieAuth: []
* parameters:
* - name: pageSize
* in: query
* schema:
* type: integer
* default: 50
* description: Number of records per page
* responses:
* '200':
* description: History data from Radarr
* content:
* application/json:
* schema:
* type: object
*/
// Get history
router.get('/history', async (req, res) => {
try {
@@ -66,6 +114,36 @@ router.get('/movies', async (req, res) => {
}
});
/**
* @openapi
* /api/radarr/notifications/sofarr-webhook:
* post:
* tags: [Radarr]
* summary: Configure Sofarr webhook
* description: One-click setup for Sofarr webhook notification in Radarr. Requires authentication and CSRF token.
* security:
* - CookieAuth: []
* - CsrfToken: []
* responses:
* '200':
* description: Configured notification
* content:
* application/json:
* schema:
* type: object
* '400':
* description: Missing configuration
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* '503':
* description: Radarr not configured
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
// Notification proxy routes (Phase 3)
// GET /api/radarr/notifications - list all notifications
router.get('/notifications', async (req, res) => {
server/routes/sabnzbd.js
+49 -2
View File
@@ -5,9 +5,32 @@ const router = express.Router();
const requireAuth = require('../middleware/requireAuth');
const sanitizeError = require('../utils/sanitizeError');
/**
* @openapi
* /api/sabnzbd/queue:
* get:
* tags: [SABnzbd]
* summary: Get SABnzbd queue
* description: Proxy to SABnzbd's queue endpoint. Requires authentication.
* security:
* - CookieAuth: []
* responses:
* '200':
* description: Queue data from SABnzbd
* content:
* application/json:
* schema:
* type: object
* '500':
* description: Proxy error
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
router.use(requireAuth);
// Get current queue
// GET /api/sabnzbd/queue
router.get('/queue', async (req, res) => {
try {
const response = await axios.get(`${process.env.SABNZBD_URL}/api`, {
@@ -23,7 +46,31 @@ router.get('/queue', async (req, res) => {
}
});
// Get history
/**
* @openapi
* /api/sabnzbd/history:
* get:
* tags: [SABnzbd]
* summary: Get SABnzbd history
* description: Proxy to SABnzbd's history endpoint. Requires authentication.
* security:
* - CookieAuth: []
* parameters:
* - name: limit
* in: query
* schema:
* type: integer
* default: 50
* description: Number of history records to return
* responses:
* '200':
* description: History data from SABnzbd
* content:
* application/json:
* schema:
* type: object
*/
// GET /api/sabnzbd/history
router.get('/history', async (req, res) => {
try {
const response = await axios.get(`${process.env.SABNZBD_URL}/api`, {
server/routes/sonarr.js
+78
View File
@@ -15,6 +15,30 @@ function getFirstSonarrInstance() {
return instances[0];
}
/**
* @openapi
* /api/sonarr/queue:
* get:
* tags: [Sonarr]
* summary: Get Sonarr queue
* description: Proxy to Sonarr's queue endpoint. Requires authentication and CSRF token.
* security:
* - CookieAuth: []
* - CsrfToken: []
* responses:
* '200':
* description: Queue data from Sonarr
* content:
* application/json:
* schema:
* type: object
* '500':
* description: Proxy error
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
router.use(requireAuth);
// Get queue
@@ -29,6 +53,30 @@ router.get('/queue', async (req, res) => {
}
});
/**
* @openapi
* /api/sonarr/history:
* get:
* tags: [Sonarr]
* summary: Get Sonarr history
* description: Proxy to Sonarr's history endpoint. Requires authentication.
* security:
* - CookieAuth: []
* parameters:
* - name: pageSize
* in: query
* schema:
* type: integer
* default: 50
* description: Number of records per page
* responses:
* '200':
* description: History data from Sonarr
* content:
* application/json:
* schema:
* type: object
*/
// Get history
router.get('/history', async (req, res) => {
try {
@@ -66,6 +114,36 @@ router.get('/series', async (req, res) => {
}
});
/**
* @openapi
* /api/sonarr/notifications/sofarr-webhook:
* post:
* tags: [Sonarr]
* summary: Configure Sofarr webhook
* description: One-click setup for Sofarr webhook notification in Sonarr. Requires authentication and CSRF token.
* security:
* - CookieAuth: []
* - CsrfToken: []
* responses:
* '200':
* description: Configured notification
* content:
* application/json:
* schema:
* type: object
* '400':
* description: Missing configuration
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* '503':
* description: Sonarr not configured
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
*/
// Notification proxy routes (Phase 3)
// GET /api/sonarr/notifications - list all notifications
router.get('/notifications', async (req, res) => {