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>

server/src/app.js

@@ -7,6 +7,8 @@ const morgan = require('morgan')
 const cookieParser = require('cookie-parser')
 require('dotenv').config()
 
+const swaggerUi = require('swagger-ui-express')
+
 const apiRouter = require('./router/api.router')
 const createLogger = require('./utils/logger')
 const { applyTrustProxy, trustProxyDebug } = require('./utils/trustProxy')
@@ -75,8 +77,35 @@ app.use(
   }),
 )
 
+// ── API docs (Swagger UI) ─────────────────────────────────────────────
+// Interactive OpenAPI docs at /api/docs, raw spec at /api/docs.json. The spec
+// is generated from route annotations by `npm run swagger` (server/swagger/).
+// Loaded lazily and guarded so a missing spec never crashes the server.
+try {
+  // eslint-disable-next-line global-require
+  const swaggerSpec = require('../swagger/swagger-output.json')
+  app.get('/api/docs.json', (req, res) => {
+    // #swagger.ignore = true
+    res.json(swaggerSpec)
+  })
+  app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
+    customSiteTitle: 'UOMysticmoon API docs',
+    swaggerOptions: { persistAuthorization: true },
+  }))
+} catch (err) {
+  errLog.error('Swagger spec not found — run `npm run swagger` to generate it. API docs disabled.', {
+    message: err.message,
+  })
+}
+
 // ── API ───────────────────────────────────────────────────────────────
-app.get('/api/health', (req, res) => res.json({ status: 'ok' }))
+app.get(
+  '/api/health',
+  // #swagger.tags = ['Health']
+  // #swagger.summary = 'Liveness probe'
+  /* #swagger.responses[200] = { description: 'Service is up', content: { "application/json": { schema: { type: "object", properties: { status: { type: "string", example: "ok" } } } } } } */
+  (req, res) => res.json({ status: 'ok' }),
+)
 app.use('/api', apiRouter)
 app.use('/api', (req, res) => res.status(404).json({ message: 'Not found' }))