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' }))
 

server/src/router/v1/admin/admin.routes.js

@@ -24,25 +24,72 @@ const adminOnly = requireRole('admin')
 
 // ── Account security (self-service, any logged-in role) ───────────────
 // Not behind adminOnly: an editor manages their own 2FA too.
-adminRouter.get('/account', account.getAccount)
-adminRouter.post('/account/totp/setup', account.totpSetup)
+adminRouter.get(
+  '/account',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Get the current account (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The account', content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  account.getAccount,
+)
+adminRouter.post(
+  '/account/totp/setup',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Begin 2FA enrollment (returns secret + QR)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'otpauth URL and QR data to scan', content: { "application/json": { schema: { type: "object", properties: { otpauth_url: { type: "string" }, qr: { type: "string" } } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  account.totpSetup,
+)
 adminRouter.post(
   '/account/totp/enable',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Enable 2FA by confirming a code'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
+  /* #swagger.responses[200] = { description: '2FA enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Setup not started, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('code').isString().trim().isLength({ min: 6, max: 8 }),
   validate,
   account.totpEnable,
 )
 adminRouter.post(
   '/account/totp/disable',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Disable 2FA by confirming a code'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
+  /* #swagger.responses[200] = { description: '2FA disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Not enabled, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('code').isString().trim().isLength({ min: 6, max: 8 }),
   validate,
   account.totpDisable,
 )
 
 // Linked SSO identities (self-service — any logged-in role manages their own).
-adminRouter.get('/account/identities', account.listIdentities)
+adminRouter.get(
+  '/account/identities',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'List linked SSO identities (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Linked identities', content: { "application/json": { schema: { type: "array", items: { type: "object", properties: { provider: { type: "string" }, email: { type: "string" } } } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  account.listIdentities,
+)
 adminRouter.delete(
   '/account/identities/:provider',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Unlink an SSO identity (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
+  /* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'No linked account for that provider', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   param('provider').matches(/^[a-z0-9-]+$/),
   validate,
   account.unlinkIdentity,
@@ -83,9 +130,26 @@ const upload = multer({
 })
 
 // ── Dashboard & site mode ─────────────────────────────────────────────
-adminRouter.get('/dashboard', ctrl.dashboard)
+adminRouter.get(
+  '/dashboard',
+  // #swagger.tags = ['Admin · Dashboard']
+  // #swagger.summary = 'Dashboard summary counts'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Summary counts (posts, wiki, users, site mode)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.dashboard,
+)
 adminRouter.put(
   '/site-mode',
+  // #swagger.tags = ['Admin · Dashboard']
+  // #swagger.summary = 'Set site mode (admin only)'
+  // #swagger.description = 'Switch the site between live and maintenance.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SiteModeRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated site mode', content: { "application/json": { schema: { type: "object", properties: { mode: { type: "string", example: "maintenance" } } } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   adminOnly,
   body('mode').isIn(['live', 'maintenance']),
   validate,
@@ -93,32 +157,133 @@ adminRouter.put(
 )
 
 // ── Posts (news / five-on-friday / newsletter / screenshots) ──────────
-adminRouter.get('/posts', ctrl.listPosts)
+adminRouter.get(
+  '/posts',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'List all posts (including unpublished)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['category'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Optional category filter.' }
+  /* #swagger.responses[200] = { description: 'Posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listPosts,
+)
 adminRouter.post(
   '/posts',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Create a post'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PostCreateRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Created post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('category').isString().notEmpty(),
   body('title').isString().trim().notEmpty().isLength({ max: 200 }),
   validate,
   ctrl.createPost,
 )
-adminRouter.post('/posts/upload', upload.single('image'), ctrl.uploadImage)
+adminRouter.post(
+  '/posts/upload',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Upload a post image (multipart)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "multipart/form-data": { schema: { type: "object", properties: { image: { type: "string", format: "binary" } } } } } } */
+  /* #swagger.responses[201] = { description: 'Stored image URL', content: { "application/json": { schema: { type: "object", properties: { image_url: { type: "string", example: "/uploads/1700000000-abcd.png" } } } } } } */
+  /* #swagger.responses[400] = { description: 'No image / disallowed type', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  upload.single('image'),
+  ctrl.uploadImage,
+)
 // Generalized upload (rich-text editors). Same multer middleware; returns { url }.
-adminRouter.post('/uploads', upload.single('image'), ctrl.uploadFile)
-adminRouter.get('/posts/:id', param('id').isInt(), validate, ctrl.getPost)
-adminRouter.put('/posts/:id', param('id').isInt(), validate, ctrl.updatePost)
+adminRouter.post(
+  '/uploads',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Upload an image for rich-text editors (multipart)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "multipart/form-data": { schema: { type: "object", properties: { image: { type: "string", format: "binary" } } } } } } */
+  /* #swagger.responses[201] = { description: 'Stored file URL', content: { "application/json": { schema: { $ref: "#/components/schemas/UploadResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'No file / disallowed type', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  upload.single('image'),
+  ctrl.uploadFile,
+)
+adminRouter.get(
+  '/posts/:id',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Get a post by id'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Post id.' }
+  /* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.getPost,
+)
+adminRouter.put(
+  '/posts/:id',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Update a post'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Post id.' }
+  /* #swagger.requestBody = { content: { "application/json": { schema: { $ref: "#/components/schemas/PostCreateRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.updatePost,
+)
 adminRouter.patch(
   '/posts/:id/publish',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Publish / unpublish a post'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Post id.' }
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PublishRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   param('id').isInt(),
   body('published').isBoolean(),
   validate,
   ctrl.publishPost,
 )
-adminRouter.delete('/posts/:id', param('id').isInt(), validate, ctrl.deletePost)
+adminRouter.delete(
+  '/posts/:id',
+  // #swagger.tags = ['Admin · Posts']
+  // #swagger.summary = 'Delete a post'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Post id.' }
+  /* #swagger.responses[200] = { description: 'Deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.deletePost,
+)
 
 // ── Wiki categories (static paths registered before /wiki/:slug) ───────
-adminRouter.get('/wiki/categories', ctrl.listWikiCategories)
+adminRouter.get(
+  '/wiki/categories',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'List wiki categories'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listWikiCategories,
+)
 adminRouter.post(
   '/wiki/categories',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Create a wiki category'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WikiCategoryCreateRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Created category', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiCategory" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Slug already exists', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('slug').matches(/^[a-z0-9-]+$/),
   body('title').isString().trim().notEmpty().isLength({ max: 200 }),
   body('description').optional({ values: 'falsy' }).isString().isLength({ max: 400 }),
@@ -128,6 +293,16 @@ adminRouter.post(
 )
 adminRouter.put(
   '/wiki/categories/:id',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Update a wiki category'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Category id.' }
+  /* #swagger.requestBody = { content: { "application/json": { schema: { $ref: "#/components/schemas/WikiCategoryCreateRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated category', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiCategory" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Slug already exists', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   param('id').isInt(),
   body('slug').optional().matches(/^[a-z0-9-]+$/),
   body('title').optional().isString().trim().notEmpty().isLength({ max: 200 }),
@@ -136,15 +311,51 @@ adminRouter.put(
   validate,
   ctrl.updateWikiCategory,
 )
-adminRouter.delete('/wiki/categories/:id', param('id').isInt(), validate, ctrl.deleteWikiCategory)
+adminRouter.delete(
+  '/wiki/categories/:id',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Delete a wiki category'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Category id.' }
+  /* #swagger.responses[200] = { description: 'Deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.deleteWikiCategory,
+)
 
 // ── Wiki tags ──────────────────────────────────────────────────────────
-adminRouter.get('/wiki/tags', ctrl.listWikiTags)
+adminRouter.get(
+  '/wiki/tags',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'List wiki tags'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listWikiTags,
+)
 
 // ── Wiki pages ─────────────────────────────────────────────────────────
-adminRouter.get('/wiki', ctrl.listWiki)
+adminRouter.get(
+  '/wiki',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'List all wiki pages (including unpublished)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listWiki,
+)
 adminRouter.post(
   '/wiki',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Create a wiki page'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPageCreateRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Created wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Slug already exists', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('slug').matches(/^[a-z0-9-]+$/),
   body('title').isString().trim().notEmpty().isLength({ max: 200 }),
   body('excerpt').optional({ values: 'falsy' }).isString().isLength({ max: 400 }),
@@ -154,9 +365,28 @@ adminRouter.post(
   validate,
   ctrl.createWiki,
 )
-adminRouter.get('/wiki/:slug', ctrl.getWiki)
+adminRouter.get(
+  '/wiki/:slug',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Get a wiki page by slug'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.getWiki,
+)
 adminRouter.put(
   '/wiki/:slug',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Update a wiki page (creates a revision)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.requestBody = { content: { "application/json": { schema: { allOf: [ { $ref: "#/components/schemas/WikiPageCreateRequest" }, { type: "object", properties: { change_note: { type: "string", maxLength: 280 } } } ] } } } } */
+  /* #swagger.responses[200] = { description: 'Updated wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('title').optional().isString().trim().notEmpty().isLength({ max: 200 }),
   body('excerpt').optional({ values: 'falsy' }).isString().isLength({ max: 400 }),
   body('category_id').optional({ values: 'null' }).isInt(),
@@ -168,33 +398,132 @@ adminRouter.put(
 )
 adminRouter.patch(
   '/wiki/:slug/publish',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Publish / unpublish a wiki page'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PublishRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('published').isBoolean(),
   validate,
   ctrl.publishWiki,
 )
-adminRouter.get('/wiki/:slug/revisions', ctrl.listWikiRevisions)
-adminRouter.get('/wiki/:slug/revisions/:id', param('id').isInt(), validate, ctrl.getWikiRevision)
+adminRouter.get(
+  '/wiki/:slug/revisions',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'List revisions of a wiki page'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.responses[200] = { description: 'Revisions', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listWikiRevisions,
+)
+adminRouter.get(
+  '/wiki/:slug/revisions/:id',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Get a single wiki revision'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Revision id.' }
+  /* #swagger.responses[200] = { description: 'The revision', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.getWikiRevision,
+)
 adminRouter.post(
   '/wiki/:slug/revisions/:id/restore',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Restore a wiki page to a revision'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Revision id to restore.' }
+  /* #swagger.responses[200] = { description: 'Restored wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   param('id').isInt(),
   validate,
   ctrl.restoreWikiRevision,
 )
-adminRouter.delete('/wiki/:slug', ctrl.deleteWiki)
+adminRouter.delete(
+  '/wiki/:slug',
+  // #swagger.tags = ['Admin · Wiki']
+  // #swagger.summary = 'Delete a wiki page'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.responses[200] = { description: 'Deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.deleteWiki,
+)
 
 // ── Settings ──────────────────────────────────────────────────────────
-adminRouter.get('/settings', adminOnly, ctrl.getSettings)
-adminRouter.put('/settings', adminOnly, ctrl.updateSettings)
+adminRouter.get(
+  '/settings',
+  // #swagger.tags = ['Admin · Settings']
+  // #swagger.summary = 'Get all site settings (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'All settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  ctrl.getSettings,
+)
+adminRouter.put(
+  '/settings',
+  // #swagger.tags = ['Admin · Settings']
+  // #swagger.summary = 'Update site settings (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", additionalProperties: true, description: "An object of key/value settings." } } } } */
+  /* #swagger.responses[200] = { description: 'Updated settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Body must be an object of key/value settings', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  ctrl.updateSettings,
+)
 
 // ── Activity log ──────────────────────────────────────────────────────
-adminRouter.get('/activity', ctrl.listActivity)
+adminRouter.get(
+  '/activity',
+  // #swagger.tags = ['Admin · Activity']
+  // #swagger.summary = 'List recent admin activity'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max rows to return.' }
+  /* #swagger.responses[200] = { description: 'Activity entries', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listActivity,
+)
 
 // ── Bot activity (admin only) ─────────────────────────────────────────
 // Read-only view of the botScore middleware's in-memory scoring/ban state and
 // recent events, plus an emergency unban for false positives.
-adminRouter.get('/bot-activity', adminOnly, botActivity.getBotActivity)
+adminRouter.get(
+  '/bot-activity',
+  // #swagger.tags = ['Admin · Bot Activity']
+  // #swagger.summary = 'Bot-scoring / ban state and recent events (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Banned IPs, scores and recent events', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  botActivity.getBotActivity,
+)
 adminRouter.post(
   '/bot-activity/unban',
+  // #swagger.tags = ['Admin · Bot Activity']
+  // #swagger.summary = 'Emergency unban an IP (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/UnbanRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Unbanned', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Invalid IP', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   adminOnly,
   body('ip').isIP(),
   validate,
@@ -202,9 +531,29 @@ adminRouter.post(
 )
 
 // ── Authentication providers / SSO (admin only) ───────────────────────
-adminRouter.get('/auth/providers', adminOnly, authProviders.list)
+adminRouter.get(
+  '/auth/providers',
+  // #swagger.tags = ['Admin · Auth Providers']
+  // #swagger.summary = 'List configured SSO providers (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Providers (secrets stripped)', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ProviderConfig" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  authProviders.list,
+)
 adminRouter.post(
   '/auth/providers',
+  // #swagger.tags = ['Admin · Auth Providers']
+  // #swagger.summary = 'Create a custom SSO provider (admin only)'
+  // #swagger.description = 'Built-in providers (google, discord) are configured via PUT, not created here.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ProviderCreateRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Created provider', content: { "application/json": { schema: { $ref: "#/components/schemas/ProviderConfig" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error, or a built-in/invalid kind', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Provider id already exists', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   adminOnly,
   body('id').matches(/^[a-z0-9-]+$/),
   body('kind').isIn(['oidc', 'oauth2']),
@@ -222,6 +571,16 @@ adminRouter.post(
 )
 adminRouter.put(
   '/auth/providers/:id',
+  // #swagger.tags = ['Admin · Auth Providers']
+  // #swagger.summary = 'Update an SSO provider (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
+  /* #swagger.requestBody = { content: { "application/json": { schema: { $ref: "#/components/schemas/ProviderCreateRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated provider', content: { "application/json": { schema: { $ref: "#/components/schemas/ProviderConfig" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Provider not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   adminOnly,
   param('id').matches(/^[a-z0-9-]+$/),
   body('name').optional().isString().trim().notEmpty().isLength({ max: 80 }),
@@ -238,6 +597,16 @@ adminRouter.put(
 )
 adminRouter.delete(
   '/auth/providers/:id',
+  // #swagger.tags = ['Admin · Auth Providers']
+  // #swagger.summary = 'Delete a custom SSO provider (admin only)'
+  // #swagger.description = 'Built-in providers cannot be deleted — disable them instead.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
+  /* #swagger.responses[200] = { description: 'Deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Built-in provider cannot be deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Provider not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   adminOnly,
   param('id').matches(/^[a-z0-9-]+$/),
   validate,
@@ -246,9 +615,27 @@ adminRouter.delete(
 
 // ── User management (admin only) ──────────────────────────────────────
 adminRouter.use('/users', adminOnly)
-adminRouter.get('/users', ctrl.listUsers)
+adminRouter.get(
+  '/users',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'List users (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Users', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/User" } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listUsers,
+)
 adminRouter.post(
   '/users',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Create a user (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/UserCreateRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Created user', content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   body('username').isString().trim().isLength({ min: 3, max: 32 }),
   body('password').isString().isLength({ min: 8, max: 64 }),
   body('role').optional().isIn(['admin', 'editor']),
@@ -257,6 +644,17 @@ adminRouter.post(
 )
 adminRouter.put(
   '/users/:id',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Update a user (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.requestBody = { content: { "application/json": { schema: { $ref: "#/components/schemas/UserCreateRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated user', content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error, or cannot demote the last admin', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   param('id').isInt(),
   body('username').optional().isString().trim().isLength({ min: 3, max: 32 }),
   body('password').optional().isString().isLength({ min: 8, max: 64 }),
@@ -264,6 +662,20 @@ adminRouter.put(
   validate,
   ctrl.updateUser,
 )
-adminRouter.delete('/users/:id', param('id').isInt(), validate, ctrl.deleteUser)
+adminRouter.delete(
+  '/users/:id',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Delete a user (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Deleted', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Cannot delete your own account or the last admin', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  ctrl.deleteUser,
+)
 
 module.exports = adminRouter

server/src/router/v1/auth/auth.routes.js

@@ -26,6 +26,14 @@ const loginGuards = [backoffGuard, slowLogin, loginLimiter]
 
 authRouter.post(
   '/login',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Log in with username and password'
+  // #swagger.description = 'On success sets the httpOnly session cookie. If the account has 2FA enabled, returns { totpRequired, challenge } instead and no cookie is set — complete login at POST /login/totp. Rate limited and behind bot/backoff guards.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/LoginRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued, or TOTP challenge required', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Incorrect username or password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   ...loginGuards,
   body('username').isString().trim().notEmpty(),
   body('password').isString().notEmpty(),
@@ -39,6 +47,14 @@ authRouter.post(
 // Second factor: same throttling, since it's a code-guessing surface too.
 authRouter.post(
   '/login/totp',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Complete login with a TOTP code'
+  // #swagger.description = 'Second step for 2FA accounts. Exchange the challenge from /login plus the current authenticator code for a session cookie.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpLoginRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Invalid code or expired challenge', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   ...loginGuards,
   body('challenge').isString().notEmpty(),
   body('code').isString().trim().isLength({ min: 6, max: 8 }),
@@ -46,7 +62,22 @@ authRouter.post(
   loginTotp,
 )
 
-authRouter.post('/logout', logout)
-authRouter.get('/me', isLoggedIn, me)
+authRouter.post(
+  '/logout',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Log out (clear the session cookie)'
+  /* #swagger.responses[200] = { description: 'Logged out', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  logout,
+)
+authRouter.get(
+  '/me',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Current authenticated user'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The signed-in user', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/User" } } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  isLoggedIn,
+  me,
+)
 
 module.exports = authRouter

server/src/router/v1/auth/mobile.routes.js

@@ -17,6 +17,14 @@ const loginGuards = [backoffGuard, slowLogin, loginLimiter]
 // POST /auth/mobile/login — { username, password, code? }
 mobileRouter.post(
   '/login',
+  // #swagger.tags = ['Auth · Mobile']
+  // #swagger.summary = 'Native login → access + refresh tokens'
+  // #swagger.description = 'Bearer-token login for native clients. Single-request 2FA: if the account has TOTP on and no/invalid code is supplied, returns 401 { totpRequired: true } and the client retries with a code.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/MobileLoginRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Access + refresh tokens', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Invalid credentials, or a TOTP code is required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   ...loginGuards,
   body('username').isString().trim().notEmpty(),
   body('password').isString().notEmpty(),
@@ -29,6 +37,14 @@ mobileRouter.post(
 // POST /auth/mobile/refresh — { refreshToken }
 mobileRouter.post(
   '/refresh',
+  // #swagger.tags = ['Auth · Mobile']
+  // #swagger.summary = 'Rotate a refresh token for a fresh token pair'
+  // #swagger.description = 'Refresh tokens are single-use: the presented token is revoked and a new access + refresh pair is issued. Reusing a rotated token fails with 401.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/MobileRefreshRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'New access + refresh tokens', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Invalid or expired session', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many refresh attempts', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   mobileRefreshLimiter,
   body('refreshToken').isString().notEmpty(),
   validate,
@@ -38,6 +54,13 @@ mobileRouter.post(
 // POST /auth/mobile/logout — { refreshToken?, all? } — requires a valid bearer.
 mobileRouter.post(
   '/logout',
+  // #swagger.tags = ['Auth · Mobile']
+  // #swagger.summary = 'Revoke the current (or all) refresh tokens'
+  // #swagger.description = 'Requires a valid bearer access token. Revokes the given refresh token, or every session for the user when { all: true }. Idempotent.'
+  // #swagger.security = [{ "bearerAuth": [] }]
+  /* #swagger.requestBody = { content: { "application/json": { schema: { $ref: "#/components/schemas/MobileLogoutRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Logged out', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[401] = { description: 'Missing or invalid bearer token', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   requireAuth,
   body('refreshToken').optional().isString(),
   body('all').optional().isBoolean(),

server/src/router/v1/auth/sso.routes.js

@@ -7,16 +7,54 @@ const { ssoStartLimiter } = require('../../../middleware/rateLimit')
 const ssoRouter = express.Router()
 
 // Public discovery — the login page reads this to render provider buttons.
-ssoRouter.get('/providers', ctrl.listProviders)
+ssoRouter.get(
+  '/providers',
+  // #swagger.tags = ['Auth · SSO']
+  // #swagger.summary = 'List enabled SSO providers'
+  // #swagger.description = 'Public discovery used by the login page to render provider buttons. Never exposes secrets.'
+  /* #swagger.responses[200] = { description: 'Enabled, valid providers', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Provider" } } } } } */
+  ctrl.listProviders,
+)
 
 // Begin login (public) — redirects to the IdP.
-ssoRouter.get('/sso/:provider/start', ssoStartLimiter, ctrl.start)
+ssoRouter.get(
+  '/sso/:provider/start',
+  // #swagger.tags = ['Auth · SSO']
+  // #swagger.summary = 'Begin SSO login (redirect to the IdP)'
+  // #swagger.description = 'Sets a short-lived signed transaction cookie and 302-redirects to the provider authorize URL. On error redirects back to the login page with an sso_error query param.'
+  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id (e.g. google, discord).' }
+  // #swagger.parameters['returnTo'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Internal /admin path to return to after login.' }
+  /* #swagger.responses[302] = { description: 'Redirect to the identity provider (or back to the login page on error)' } */
+  ssoStartLimiter,
+  ctrl.start,
+)
 
 // Begin account linking (must be signed in — the tx captures the acting user).
-ssoRouter.get('/sso/:provider/link', requireAuth, ctrl.linkStart)
+ssoRouter.get(
+  '/sso/:provider/link',
+  // #swagger.tags = ['Auth · SSO']
+  // #swagger.summary = 'Begin linking an SSO identity to the current account'
+  // #swagger.description = 'Requires an authenticated session; the signed transaction captures the acting user so the callback can attach the external identity.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id (e.g. google, discord).' }
+  /* #swagger.responses[302] = { description: 'Redirect to the identity provider (or back to the account page on error)' } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  requireAuth,
+  ctrl.linkStart,
+)
 
 // OAuth redirect target — completes login or linking. Not behind requireAuth:
 // the signed tx cookie authorizes link mode; login mode is link-only anyway.
-ssoRouter.get('/sso/:provider/callback', ctrl.callback)
+ssoRouter.get(
+  '/sso/:provider/callback',
+  // #swagger.tags = ['Auth · SSO']
+  // #swagger.summary = 'OAuth redirect target — completes login or linking'
+  // #swagger.description = 'The provider redirects here with code + state. On success sets the session cookie (login) or links the identity (link), then 302-redirects into /admin. Login is link-only: unknown identities are refused (sso_error=not_linked).'
+  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id (e.g. google, discord).' }
+  // #swagger.parameters['code'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'OAuth authorization code.' }
+  // #swagger.parameters['state'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'OAuth state (matched against the tx cookie).' }
+  /* #swagger.responses[302] = { description: 'Redirect into /admin on success, or back to login/account with an error code' } */
+  ctrl.callback,
+)
 
 module.exports = ssoRouter

server/src/router/v1/public/public.routes.js

@@ -9,10 +9,32 @@ const { contactLimiter } = require('../../../middleware/rateLimit')
 const publicRouter = express.Router()
 
 // Always available (so the client can render the maintenance page + contact).
-publicRouter.get('/settings', ctrl.getSettings)
-publicRouter.get('/status', ctrl.getStatus)
+publicRouter.get(
+  '/settings',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Public site settings'
+  // #swagger.description = 'Whitelisted, non-sensitive settings the client needs to render the site.'
+  /* #swagger.responses[200] = { description: 'Key/value settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  ctrl.getSettings,
+)
+publicRouter.get(
+  '/status',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Site mode / status'
+  // #swagger.description = 'Current site mode (live or maintenance) so the client can show the maintenance page.'
+  /* #swagger.responses[200] = { description: 'Site status', content: { "application/json": { schema: { type: "object", properties: { mode: { type: "string", example: "live" } } } } } } */
+  ctrl.getStatus,
+)
 publicRouter.post(
   '/contact',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Send a contact message'
+  // #swagger.description = 'Emails the site owner (or falls back to a mailto). Rate limited.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContactRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Message sent', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many messages (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[502] = { description: 'Mail delivery failed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   contactLimiter,
   body('message').isString().trim().notEmpty().isLength({ max: 5000 }),
   body('email').optional({ values: 'falsy' }).isEmail(),
@@ -22,12 +44,62 @@ publicRouter.post(
 )
 
 // Content — gated by site mode (admins with a valid token bypass for preview).
-publicRouter.get('/posts/:category', siteMode, ctrl.getPosts)
-publicRouter.get('/posts/:category/:idOrSlug', siteMode, ctrl.getPost)
-publicRouter.get('/wiki', siteMode, ctrl.getWikiList)
+publicRouter.get(
+  '/posts/:category',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List published posts in a category'
+  // #swagger.description = 'Gated by site mode: during maintenance only admins with a valid session see content.'
+  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'news | five-on-friday | newsletter | screenshots' }
+  /* #swagger.responses[200] = { description: 'Published posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPosts,
+)
+publicRouter.get(
+  '/posts/:category/:idOrSlug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a single published post'
+  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Post category.' }
+  // #swagger.parameters['idOrSlug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Numeric id or slug.' }
+  /* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown category or post not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPost,
+)
+publicRouter.get(
+  '/wiki',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List published wiki pages'
+  /* #swagger.responses[200] = { description: 'Published wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
+  siteMode,
+  ctrl.getWikiList,
+)
 // Static paths must precede the :slug route so they aren't captured as a slug.
-publicRouter.get('/wiki/categories', siteMode, ctrl.getWikiCategories)
-publicRouter.get('/wiki/tags', siteMode, ctrl.getWikiTags)
-publicRouter.get('/wiki/:slug', siteMode, ctrl.getWikiPage)
+publicRouter.get(
+  '/wiki/categories',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List wiki categories'
+  /* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
+  siteMode,
+  ctrl.getWikiCategories,
+)
+publicRouter.get(
+  '/wiki/tags',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List wiki tags'
+  /* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
+  siteMode,
+  ctrl.getWikiTags,
+)
+publicRouter.get(
+  '/wiki/:slug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a single published wiki page'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getWikiPage,
+)
 
 module.exports = publicRouter