Claude
f8db61025b
The route-level annotations were 100% present, but the committed/served
spec (swagger-output.json) was stale and several response schemas had
drifted from the controllers. This aligns the docs with actual behavior
and regenerates the spec.
Served spec was stale (64/67 operations). Regenerating picks up three
routes that were added after the last generation:
- POST /api/v1/auth/sso/totp
- GET /api/v1/admin/discord-bot/config
- PUT /api/v1/admin/discord-bot/config
plus a stale /auth/logout summary.
Response-shape corrections (annotation now matches controller output):
- Mutation endpoints do NOT return the generic { message } envelope.
Deletes echo { id } / { slug }; toggles return { deleted },
{ unlinked }, { totp_enabled }, or { ip, removed }. Documented as-is
via new DeletedId/DeletedSlug/DeletedFlag/UnlinkedFlag/TotpState/
UnbanResult components. (The API is intentionally inconsistent here;
recorded rather than normalized — see follow-up note.)
- POST /account/totp/setup: otpauth_url -> otpauthUrl (TotpSetup)
- PUT /admin/site-mode: { mode } -> { site_mode, changed_at, changed_by }
- GET /account: full User -> AccountStatus (id/username/role/totp_enabled)
- GET /account/identities: add linked_at (LinkedIdentity)
- GET /public/status: add status_message (PublicStatus)
- POST /auth/sso/totp: user is SafeUser, not full User
- GET /dashboard: description/shape corrected (posts+users, no wiki)
Schema completeness:
- Provider (public discovery): { id, name, icon, loginUrl, priority },
not { id, name, kind }
- ProviderConfig: add hasSecret, builtin, health (ProviderHealth)
- Post: add excerpt, author_id, published_at
- MobileTokenResponse.expiresIn: duration string ("15m"), not integer
Config: declare the Admin · Discord Bot tag (was used but undeclared).
Auth model and the internal/external boundary were verified correct and
left unchanged: cookie + bearer are both accepted on session routes (dual
security annotations are accurate), and /internal/* runs on a separate
listener already excluded from the scan.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rao86n5cXpwAyjdBFEshV
106 lines
5.6 KiB
JavaScript
106 lines
5.6 KiB
JavaScript
const express = require('express')
|
|
const { body } = require('express-validator')
|
|
|
|
const ctrl = require('./public.controller')
|
|
const siteMode = require('../../../middleware/siteMode')
|
|
const validate = require('../../../middleware/validate')
|
|
const { contactLimiter } = require('../../../middleware/rateLimit')
|
|
|
|
const publicRouter = express.Router()
|
|
|
|
// Always available (so the client can render the maintenance page + contact).
|
|
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: { $ref: "#/components/schemas/PublicStatus" } } } } */
|
|
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(),
|
|
body('name').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
|
|
validate,
|
|
ctrl.contact,
|
|
)
|
|
|
|
// Content — gated by site mode (admins with a valid token bypass for preview).
|
|
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',
|
|
// #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
|