Add Swagger/OpenAPI API docs (swagger-ui + swagger-autogen)

Generate an OpenAPI 3.0 spec from route annotations and serve it with
Swagger UI so the full REST API is browsable and testable.

- Add swagger-ui-express (runtime) and swagger-autogen (dev) deps, plus
  an `npm run swagger` script.
- server/swagger/swagger.js: generator config with API metadata, servers,
  14 tag groups, cookie + bearer security schemes, and 28 reusable
  component schemas. Follows the Express mount chain from src/app.js so
  generated paths are fully-qualified (/api/v1/...).
- Annotate every route (auth, mobile, sso, public, admin, health) with
  #swagger tags/summaries/parameters/request bodies/security and the
  actual response codes each handler returns (400/401/403/404/409/429/
  302/502, multipart uploads).
- Serve Swagger UI at /api/docs and the raw spec at /api/docs.json,
  guarded so a missing spec disables docs instead of crashing.
- Commit the generated swagger-output.json so docs work with no build
  step; swagger-autogen stays dev-only and is not needed at runtime.
- README: new "API documentation (Swagger)" section plus tech-stack and
  project-structure entries.

Covers 51 paths / 64 operations. Existing test suite (83) still passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -23,6 +23,7 @@ The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, sc
 - [First admin & site mode](#first-admin--site-mode)
 - [Pages & routes](#pages--routes)
 - [API endpoints](#api-endpoints)
+- [API documentation (Swagger)](#api-documentation-swagger)
 - [Environment variables](#environment-variables)
 - [Security](#security)
 - [Logging](#logging)
@@ -39,6 +40,7 @@ The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, sc
 | Database | MariaDB 11 (own container) |
 | Frontend | React 18, Vite 5, React Router 6 |
 | Email | Nodemailer (SMTP) with a `mailto:` fallback |
+| API docs | OpenAPI 3.0 via `swagger-autogen`, served with `swagger-ui-express` at `/api/docs` |
 | Deploy | Docker Compose, Pangolin reverse proxy |
 
 ---
@@ -57,6 +59,7 @@ UOMSITE/
 │  │  ├─ middleware/           siteMode · noindex · rateLimit · loginProtection · botScore · validate
 │  │  └─ utils/                auth (compat facade) · totp (2FA) · secretBox (AES-GCM secrets) · db (pool) · mailer · logger
 │  ├─ db/                      schema.sql + seed.js
+│  ├─ swagger/                 swagger.js (OpenAPI generator config) + swagger-output.json (generated spec)
 │  └─ .env.example
 ├─ client/                     React + Vite SPA
 │  ├─ src/
@@ -207,7 +210,44 @@ npm start               # node server → serves API + SPA at http://localhost:3
 
 Post categories (URL form): `news`, `five-on-friday`, `newsletter`, `screenshots`.
 `authMethod` on a session ∈ `local · totp · mobile · google · discord · oidc`.
-See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) §4 for the full contract.
+See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) §4 for the full contract, or the interactive Swagger
+docs below for a per-endpoint reference (parameters, request bodies, response codes).
+
+---
+
+## API documentation (Swagger)
+
+The full API is documented as an **OpenAPI 3.0** spec and served with **Swagger UI**:
+
+| URL | What |
+|---|---|
+| `http://localhost:3000/api/docs` | Interactive Swagger UI (try-it-out, auth) |
+| `http://localhost:3000/api/docs.json` | Raw OpenAPI 3.0 spec (JSON) |
+
+Every endpoint is tagged and grouped (Auth, Auth · Mobile, Auth · SSO, Public, and the Admin
+groups) with its summary, parameters, request body, security requirement, and the response codes it
+actually returns (`400` validation, `401`/`403` auth, `404`, `409` conflicts, `429` rate limits, …).
+
+**Authentication in the UI** — click **Authorize** and provide either:
+
+- `cookieAuth` — the `uomm_token` session cookie (set automatically in the browser after
+  `POST /api/v1/auth/login`), or
+- `bearerAuth` — a mobile access token from `POST /api/v1/auth/mobile/login` (sent as
+  `Authorization: Bearer <token>`).
+
+**Regenerating the spec** — the spec is generated from `#swagger.*` annotations next to each route
+(`server/src/router/**`) plus the shared definitions in `server/swagger/swagger.js`
+([swagger-autogen](https://github.com/davibaltar/swagger-autogen)). The output
+`server/swagger/swagger-output.json` is committed so the docs work with no build step. After adding
+or changing a route, regenerate it:
+
+```bash
+cd server
+npm run swagger        # → server/swagger/swagger-output.json
+```
+
+If the generated spec is missing, the server logs a warning and simply disables `/api/docs` (it does
+not crash).
 
 ---