From e254873beee51c211e937639cc9ce4bde10ec055 Mon Sep 17 00:00:00 2001 From: Gronod Date: Thu, 21 May 2026 12:39:45 +0100 Subject: [PATCH] docs(swagger): document Swagger UI and hybrid approach - Add section on accessing Swagger UI at /api/swagger - Explain hybrid documentation: central YAML + JSDoc merge - Document authentication flow for testing in Swagger UI - Include cookie + CSRF token setup instructions - Note that proxy routes reflect upstream *arr APIs --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index ffd54a0..cb926d5 100644 --- a/README.md +++ b/README.md @@ -353,6 +353,49 @@ sofarr polls all configured services in the background and caches the results. D - **Peers** - Number of peers - **Availability** - Percentage available in swarm (shown in red when below 100%) +## API Documentation (Swagger UI) + +sofarr provides interactive API documentation via Swagger UI, available at: + +**`http://your-server:3001/api/swagger`** + +### Authentication in Swagger UI + +sofarr uses cookie-based authentication with Emby/Jellyfin. To test authenticated endpoints in Swagger UI: + +1. **Login via Swagger UI:** + - Expand `POST /api/auth/login` + - Click "Try it out" + - Enter your Emby username and password + - Click "Execute" + - The browser will automatically save the session cookies + +2. **For state-changing requests (POST/PUT/PATCH/DELETE):** + - Swagger UI automatically includes the `X-CSRF-Token` header from your cookies + - No manual header configuration needed + +3. **For GET requests:** + - Cookies are sent automatically + - No additional configuration needed + +### Hybrid Documentation Approach + +sofarr uses a hybrid documentation model to maintain clean, maintainable API documentation: + +- **Central OpenAPI Specification (`server/openapi.yaml`)**: Contains base metadata, security schemes, component schemas (NormalizedDownload, DashboardPayload, ErrorResponse, etc.), and path definitions. This is the single source of truth for shared data structures and global configuration. + +- **JSDoc `@openapi` Comments in Route Files**: Per-endpoint details are documented directly in the route handler files (`server/routes/*.js`) using JSDoc `@openapi` comments. swagger-jsdoc merges these comments with the central YAML at runtime, keeping documentation close to the code while maintaining a clean separation of concerns. + +This approach provides: +- **Maintainability**: Endpoint details live alongside the code they document +- **Consistency**: Shared schemas are defined once in the central YAML +- **Flexibility**: Easy to update documentation when code changes +- **Machine-Usability**: Full JSON Schema with realistic examples, code samples, and integration notes for AI agents and automated tools + +### Proxy Routes + +The proxy routes (`/api/sonarr/**`, `/api/radarr/**`, `/api/sabnzbd/**`, `/api/emby/**) are authenticated proxies to upstream services. These endpoints reflect the APIs of Sonarr, Radarr, SABnzbd, and Emby respectively, and are documented to show the specific endpoints implemented in sofarr (not the full upstream API surface). + ## API Endpoints ### Authentication