Swagger / OpenAPI

node-auth ships a built-in OpenAPI 3.0 spec covering every endpoint on the auth router, admin router, and tools router. Swagger UI is served automatically and enabled by default outside production.

---

Auth router — Swagger UI

Mount the auth router and the spec is available at:

GET /auth/docs         — Swagger UI
GET /auth/openapi.json — raw OpenAPI 3.0 spec

Enable/disable explicitly:

const auth = new AuthConfigurator(config, userStore);
app.use('/auth', auth.router());
// swagger is auto-enabled when NODE_ENV !== 'production'

---

Tools router — Swagger UI

import { createToolsRouter } from '@nik2208/node-auth';

app.use('/tools', createToolsRouter(tools, {
  swagger: 'auto',         // default — enabled outside production
  swaggerBasePath: '/tools',
}));

Endpoints:

GET /tools/docs         — Swagger UI
GET /tools/openapi.json — raw OpenAPI 3.0 spec

---

Admin router — Swagger UI

import { createAdminRouter } from '@nik2208/node-auth';

app.use('/admin', createAdminRouter(userStore, {
  adminSecret: process.env.ADMIN_SECRET!,
}));
// GET /admin/docs  — Swagger UI (auto-enabled outside production)

---

Disabling in production

The swagger option accepts:

Value	Behaviour
'auto' (default)	Enabled when NODE_ENV !== 'production'
true	Always enabled
false	Always disabled

app.use('/tools', createToolsRouter(tools, { swagger: false }));

---

Tools router endpoints

Method	Path	Description
POST	/tools/track/:eventName	Track a telemetry event
POST	/tools/notify/:target	Send an SSE notification
GET	/tools/stream	SSE stream endpoint
POST	/tools/webhook/:provider	Receive an inbound webhook
GET	/tools/telemetry	Query persisted telemetry (if store provides query)
GET	/tools/docs	Swagger UI
GET	/tools/openapi.json	Raw OpenAPI 3.0 spec

---

Using the OpenAPI spec

Import the spec into any API tool — Postman, Insomnia, Stoplight, etc.:

https://your-server.example.com/auth/openapi.json
https://your-server.example.com/tools/openapi.json
https://your-server.example.com/admin/openapi.json