mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-23 15:36:33 +00:00
Maurice
724c88c201
A mechanical prettier --write over server/src, server/tests, server/scripts and shared/src with the workspaces' .prettierrc; nothing but layout and import order changes, and every file keeps the same set of imports. shared is formatted throughout and its format baseline is empty. The server baseline keeps the 35 files that Prettier would grow past their lint:size limit (they need a split first, which is not a formatting change), and the generated entity files stay as their generator writes them.
52 lines
2.7 KiB
TypeScript
52 lines
2.7 KiB
TypeScript
import { readEnv } from '../../app-config';
|
|
import type { INestApplication } from '@nestjs/common';
|
|
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
|
|
|
|
import { cleanupOpenApiDoc } from 'nestjs-zod';
|
|
|
|
/**
|
|
* Swagger UI + OpenAPI spec for the REST API (#1412), gated behind
|
|
* TREK_API_DOCS_ENABLED. Must run BEFORE app.init() — SwaggerModule.setup
|
|
* registers Express-level routes, and a post-init Express route is
|
|
* unreachable behind the Nest router (see bootstrap.ts).
|
|
*
|
|
* /api/docs Swagger UI (all controllers, try-it-out, auth button)
|
|
* /api/docs-json raw OpenAPI 3 document (generated clients, Postman)
|
|
* /api/docs-yaml same, as YAML
|
|
*
|
|
* The bearer button works with a plain TREK session JWT: extractToken
|
|
* accepts `Authorization: Bearer` everywhere as the cookie fallback.
|
|
*/
|
|
export function setupApiDocs(app: INestApplication): void {
|
|
const version: string = readEnv().app.appVersion || (require('../../../package.json') as { version: string }).version;
|
|
const config = new DocumentBuilder()
|
|
.setTitle('TREK API')
|
|
.setDescription(
|
|
'The REST API the TREK web app itself runs on. Authenticate with a session JWT — ' +
|
|
'either the `trek_session` cookie (same browser) or an `Authorization: Bearer <jwt>` header.\n\n' +
|
|
'Every session can be ended before it expires: `POST /api/auth/logout` ends the one it is called with, ' +
|
|
'`GET /api/auth/sessions` lists the signed-in sessions, `DELETE /api/auth/sessions/{id}` ends one and ' +
|
|
'`POST /api/auth/sessions/revoke-others` ends all but the current one.\n\n' +
|
|
'**Deprecated:** the `token` field in the bodies of `POST /api/auth/login`, `/register`, `/demo-login`, ' +
|
|
'`/mfa/verify-login`, `/passkey/login/verify` and `GET /api/auth/oidc/exchange`. It is still sent, for ' +
|
|
'clients that read it, but will be removed in a future major version. Use the `trek_session` cookie the ' +
|
|
'same response sets; the SSO exchange also answers `success: true`.',
|
|
)
|
|
.setVersion(version)
|
|
.addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }, 'session')
|
|
.addCookieAuth('trek_session')
|
|
.addSecurityRequirements('session')
|
|
.build();
|
|
const rawDocument = SwaggerModule.createDocument(app, config);
|
|
// The createZodDto classes on @Body() params carry their @trek/shared Zod
|
|
// schemas into the document; cleanupOpenApiDoc (nestjs-zod) normalizes the
|
|
// zod-generated JSON Schema output — no double annotation, every validated
|
|
// body is documented.
|
|
const document = cleanupOpenApiDoc(rawDocument);
|
|
SwaggerModule.setup('api/docs', app, document, {
|
|
jsonDocumentUrl: 'api/docs-json',
|
|
yamlDocumentUrl: 'api/docs-yaml',
|
|
swaggerOptions: { persistAuthorization: true },
|
|
});
|
|
}
|