API Documentation (Swagger)

Relevant source files - app.js - config/swagger.js - public/swagger-custom.css - public/swagger-custom.js

The Subscription Tracker API utilizes Swagger (OpenAPI 3.0.0) to provide interactive, browser-based documentation. This system allows developers to visualize and interact with the API's resources without needing access to the underlying implementation.

1. Documentation Architecture

The documentation is generated dynamically by scanning JSDoc comments within the route files. This ensures that the documentation stays in sync with the actual code logic.

Documentation Generation Flow

The following diagram illustrates how JSDoc annotations are transformed into the interactive Swagger UI.

Title: Swagger Documentation Pipeline

[Flowchart Diagram]

Sources: config/swagger.js4-32 app.js32-40

2. Configuration (`config/swagger.js`)

The swagger-jsdoc configuration defines the metadata and security requirements for the API.

Key	Value / Purpose
OpenAPI Version	`3.0.0`
Servers	Dynamically set to `SERVER_URL` or `http://localhost:${PORT}`config/swagger.js12-17
Security Scheme	`bearerAuth` (HTTP Bearer / JWT) config/swagger.js19-26
Target Files	`./routes/*.js`config/swagger.js29

The bearerAuth scheme is critical for testing protected endpoints directly from the UI. It instructs the Swagger UI to include the Authorization: Bearer <token> header in requests config/swagger.js20-25

Sources: config/swagger.js1-33

3. UI Implementation and Routing

The documentation is served at the /api-docs/v1/ endpoint using swagger-ui-express.

Server Integration

In app.js, the middleware is mounted to handle the documentation requests. It uses the swaggerSpec generated in the config and applies custom assets:

Endpoint: /api-docs/v1/app.js33
Custom CSS: /swagger-custom.css (provides a dark theme) app.js36
Custom JS: /swagger-custom.js (manages UI behavior) app.js37
Site Title: "Subscription Tracker API Docs" app.js38

Title: API Endpoint Mapping

sequenceDiagram
    participant Client
    participant App as "app.js"
    participant UI as "swagger-ui-express"
    participant Spec as "swaggerSpec"
    Client->>App: GET /api-docs/v1/
    App->>UI: serve()
    UI->>Spec: Load OpenAPI JSON
    UI-->>Client: Render HTML + Custom CSS/JS

Sources: app.js4-5 app.js32-40

4. UI Customization (`public/`)

To provide a cohesive developer experience, the Swagger UI is customized via static assets located in the public/ directory.

Styling (`public/swagger-custom.css`)

The CSS overrides the default Swagger "Petstore" look with a dark theme matching the project's design language.

Design Tokens: Defines a palette of dark surfaces (--sw-dark-950) and accent colors (--sw-accent-400) public/swagger-custom.css9-31
Layout Overrides: Customizes the .topbarpublic/swagger-custom.css67-76.opblock (operation blocks) public/swagger-custom.css227-234 and typography using 'Inter' and 'JetBrains Mono' public/swagger-custom.css6-30

Behavior (`public/swagger-custom.js`)

The JavaScript file performs DOM manipulations to refine the UI:

hardenDarkMode(): Forces the document into dark mode by setting data attributes and classes public/swagger-custom.js1-6
removeThemeToggle(): Searches for and removes any default light/dark mode switches to prevent UI flickering or inconsistent states public/swagger-custom.js8-49
ensureHomeLink(): Injects a "← Home" link into the Swagger topbar to allow easy navigation back to the main landing page public/swagger-custom.js51-61

Sources: public/swagger-custom.css1-31 public/swagger-custom.js1-88

5. Annotating Routes

For an endpoint to appear in the documentation, it must be preceded by a @swagger JSDoc block in its respective route file.

Example Annotation Structure:

Tags: Groups endpoints (e.g., "Auth", "Subscriptions").
Security: Specifies if the route requires bearerAuth.
Parameters: Defines URL path or query parameters.
Responses: Lists possible HTTP status codes and their JSON schemas.

The swaggerSpec object collects these annotations by scanning the path defined in the configuration config/swagger.js29-32

Sources: config/swagger.js29-32 app.js5