Swagger UI Setup for Rclone Service

Date: 2025-10-06 Status: Implementation record; deployment URLs below reflect the current VM model

Overview

The rclone service now provides interactive API documentation via Swagger UI at http://localhost:3001/docs.

Implementation Details

Endpoints Added

1. /openapi.json - Serves the OpenAPI 3.0 specification

   • Generated from JSDoc comments in source files.
   • Updated via pnpm gen:openapi script.

2. /docs - Swagger UI interface

   • Custom HTML page with Swagger UI components.
   • Loads OpenAPI spec from /openapi.json.
   • Interactive API testing and documentation.

3. /docs/assets/* - Static assets

   • Swagger UI CSS, JavaScript, and images.
   • Served from swagger-ui-dist package.

Content Security Policy Configuration

Issue: Helmet's default CSP blocked inline scripts required by Swagger UI.

Solution: Configured Helmet with relaxed CSP directives:

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'", "'unsafe-inline'"], // Allow inline scripts for Swagger UI
        styleSrc: ["'self'", "'unsafe-inline'"], // Allow inline styles for Swagger UI
        imgSrc: ["'self'", "data:", "https:"],
      },
    },
  })
);

Security Note: The directive is only needed for the Swagger UI page. All other API endpoints maintain strict CSP. In production, consider using nonces or hashes for better security.