create-forgeon 0.1.32 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/modules/executor.mjs

@@ -4,6 +4,7 @@ import { ensureModuleExists } from './registry.mjs';
 import { writeModuleDocs } from './docs.mjs';
 import { applyI18nModule } from './i18n.mjs';
 import { applyLoggerModule } from './logger.mjs';
+import { applySwaggerModule } from './swagger.mjs';
 
 function ensureForgeonLikeProject(targetRoot) {
   const requiredPaths = [
@@ -24,6 +25,7 @@ function ensureForgeonLikeProject(targetRoot) {
 const MODULE_APPLIERS = {
   i18n: applyI18nModule,
   logger: applyLoggerModule,
+  swagger: applySwaggerModule,
 };
 
 export function applyModulePreset({ moduleId, targetRoot, packageRoot }) {

package/src/modules/executor.test.mjs

@@ -335,4 +335,135 @@ describe('addModule', () => {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
   });
+
+  it('applies swagger module on top of scaffold without i18n', () => {
+    const targetRoot = mkTmp('forgeon-module-swagger-');
+    const projectRoot = path.join(targetRoot, 'demo-swagger');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-swagger',
+        frontend: 'react',
+        db: 'prisma',
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'swagger',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+      assert.match(result.message, /applied/);
+      assert.equal(
+        fs.existsSync(path.join(projectRoot, 'packages', 'swagger', 'package.json')),
+        true,
+      );
+
+      const swaggerTsconfig = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'swagger', 'tsconfig.json'),
+        'utf8',
+      );
+      assert.match(swaggerTsconfig, /"extends": "\.\.\/\.\.\/tsconfig\.base\.node\.json"/);
+
+      const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+      assert.match(apiPackage, /@forgeon\/swagger/);
+      assert.match(apiPackage, /pnpm --filter @forgeon\/swagger build/);
+
+      const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+      assert.match(appModule, /@forgeon\/swagger/);
+      assert.match(appModule, /swaggerConfig/);
+      assert.match(appModule, /swaggerEnvSchema/);
+      assert.match(appModule, /ForgeonSwaggerModule/);
+
+      const mainTs = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'main.ts'), 'utf8');
+      assert.match(mainTs, /setupSwagger/);
+      assert.match(mainTs, /SwaggerConfigService/);
+      assert.match(mainTs, /setupSwagger\(app,\s*swaggerConfigService\)/);
+
+      const apiDockerfile = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'Dockerfile'),
+        'utf8',
+      );
+      assert.match(apiDockerfile, /COPY packages\/swagger\/package\.json packages\/swagger\/package\.json/);
+      assert.match(apiDockerfile, /COPY packages\/swagger packages\/swagger/);
+      assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/swagger build/);
+
+      const apiEnv = fs.readFileSync(path.join(projectRoot, 'apps', 'api', '.env.example'), 'utf8');
+      assert.match(apiEnv, /SWAGGER_ENABLED=false/);
+      assert.match(apiEnv, /SWAGGER_PATH=docs/);
+      assert.match(apiEnv, /SWAGGER_TITLE="Forgeon API"/);
+      assert.match(apiEnv, /SWAGGER_VERSION=1\.0\.0/);
+
+      const dockerEnv = fs.readFileSync(
+        path.join(projectRoot, 'infra', 'docker', '.env.example'),
+        'utf8',
+      );
+      assert.match(dockerEnv, /SWAGGER_ENABLED=false/);
+      assert.match(dockerEnv, /SWAGGER_PATH=docs/);
+      assert.match(dockerEnv, /SWAGGER_TITLE="Forgeon API"/);
+      assert.match(dockerEnv, /SWAGGER_VERSION=1\.0\.0/);
+
+      const compose = fs.readFileSync(path.join(projectRoot, 'infra', 'docker', 'compose.yml'), 'utf8');
+      assert.match(compose, /SWAGGER_ENABLED: \$\{SWAGGER_ENABLED\}/);
+      assert.match(compose, /SWAGGER_PATH: \$\{SWAGGER_PATH\}/);
+      assert.match(compose, /SWAGGER_TITLE: \$\{SWAGGER_TITLE\}/);
+      assert.match(compose, /SWAGGER_VERSION: \$\{SWAGGER_VERSION\}/);
+
+      const rootReadme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
+      assert.match(rootReadme, /## Swagger \/ OpenAPI Module/);
+      assert.match(rootReadme, /SWAGGER_ENABLED=false/);
+      assert.match(rootReadme, /localhost:3000\/docs/);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /Swagger \/ OpenAPI/);
+      assert.match(moduleDoc, /Status: implemented/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('applies swagger module on top of scaffold with i18n', () => {
+    const targetRoot = mkTmp('forgeon-module-swagger-i18n-');
+    const projectRoot = path.join(targetRoot, 'demo-swagger-i18n');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-swagger-i18n',
+        frontend: 'react',
+        db: 'prisma',
+        i18nEnabled: true,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'swagger',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+
+      const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+      assert.match(appModule, /load: \[coreConfig,\s*dbPrismaConfig,\s*i18nConfig,\s*swaggerConfig\]/);
+      assert.match(
+        appModule,
+        /validate: createEnvValidator\(\[coreEnvSchema,\s*dbPrismaEnvSchema,\s*i18nEnvSchema,\s*swaggerEnvSchema\]\)/,
+      );
+      assert.match(appModule, /ForgeonSwaggerModule/);
+      assert.match(appModule, /ForgeonI18nModule/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
 });

package/src/modules/registry.mjs

@@ -15,6 +15,14 @@ const MODULE_PRESETS = {
     description: 'Structured API logger with request id middleware and HTTP logging interceptor.',
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
+  swagger: {
+    id: 'swagger',
+    label: 'Swagger / OpenAPI',
+    category: 'api-documentation',
+    implemented: true,
+    description: 'OpenAPI docs setup with env-based toggle and route path.',
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
+  },
   'jwt-auth': {
     id: 'jwt-auth',
     label: 'JWT Auth',

package/src/modules/swagger.mjs

@@ -0,0 +1,321 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'swagger', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing swagger preset template: ${source}`);
+  }
+  const destination = path.join(targetRoot, relativePath);
+  copyRecursive(source, destination);
+}
+
+function ensureDependency(packageJson, name, version) {
+  if (!packageJson.dependencies) {
+    packageJson.dependencies = {};
+  }
+  packageJson.dependencies[name] = version;
+}
+
+function ensureLineAfter(content, anchorLine, lineToInsert) {
+  if (content.includes(lineToInsert)) {
+    return content;
+  }
+
+  const index = content.indexOf(anchorLine);
+  if (index < 0) {
+    return `${content.trimEnd()}\n${lineToInsert}\n`;
+  }
+
+  const insertAt = index + anchorLine.length;
+  return `${content.slice(0, insertAt)}\n${lineToInsert}${content.slice(insertAt)}`;
+}
+
+function ensureLineBefore(content, anchorLine, lineToInsert) {
+  if (content.includes(lineToInsert)) {
+    return content;
+  }
+
+  const index = content.indexOf(anchorLine);
+  if (index < 0) {
+    return `${content.trimEnd()}\n${lineToInsert}\n`;
+  }
+
+  return `${content.slice(0, index)}${lineToInsert}\n${content.slice(index)}`;
+}
+
+function upsertEnvLines(filePath, lines) {
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  }
+
+  const keys = new Set(
+    content
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.split('=')[0]),
+  );
+
+  const append = [];
+  for (const line of lines) {
+    const key = line.split('=')[0];
+    if (!keys.has(key)) {
+      append.push(line);
+    }
+  }
+
+  const next =
+    append.length > 0 ? `${content.trimEnd()}\n${append.join('\n')}\n` : `${content.trimEnd()}\n`;
+  fs.writeFileSync(filePath, next.replace(/^\n/, ''), 'utf8');
+}
+
+function ensureBuildStep(packageJson, buildCommand) {
+  if (!packageJson.scripts) {
+    packageJson.scripts = {};
+  }
+
+  const current = packageJson.scripts.predev;
+  if (typeof current !== 'string' || current.trim().length === 0) {
+    packageJson.scripts.predev = buildCommand;
+    return;
+  }
+
+  if (current.includes(buildCommand)) {
+    return;
+  }
+
+  packageJson.scripts.predev = `${buildCommand} && ${current}`;
+}
+
+function ensureLoadItem(content, itemName) {
+  const pattern = /load:\s*\[([^\]]*)\]/m;
+  const match = content.match(pattern);
+  if (!match) {
+    return content;
+  }
+
+  const rawList = match[1];
+  const items = rawList
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  if (!items.includes(itemName)) {
+    items.push(itemName);
+  }
+
+  const next = `load: [${items.join(', ')}]`;
+  return content.replace(pattern, next);
+}
+
+function ensureValidatorSchema(content, schemaName) {
+  const pattern = /validate:\s*createEnvValidator\(\[([^\]]*)\]\)/m;
+  const match = content.match(pattern);
+  if (!match) {
+    return content;
+  }
+
+  const rawList = match[1];
+  const items = rawList
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  if (!items.includes(schemaName)) {
+    items.push(schemaName);
+  }
+
+  const next = `validate: createEnvValidator([${items.join(', ')}])`;
+  return content.replace(pattern, next);
+}
+
+function patchApiPackage(targetRoot) {
+  const packagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  ensureDependency(packageJson, '@forgeon/swagger', 'workspace:*');
+  ensureBuildStep(packageJson, 'pnpm --filter @forgeon/swagger build');
+  writeJson(packagePath, packageJson);
+}
+
+function patchMain(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'main.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = ensureLineBefore(
+    content,
+    "import { NestFactory } from '@nestjs/core';",
+    "import { setupSwagger, SwaggerConfigService } from '@forgeon/swagger';",
+  );
+
+  if (!content.includes('const swaggerConfigService = app.get(SwaggerConfigService);')) {
+    content = content.replace(
+      '  const coreConfigService = app.get(CoreConfigService);',
+      `  const coreConfigService = app.get(CoreConfigService);
+  const swaggerConfigService = app.get(SwaggerConfigService);`,
+    );
+  }
+
+  if (!content.includes('setupSwagger(app, swaggerConfigService);')) {
+    content = content.replace(
+      '  app.useGlobalFilters(app.get(CoreExceptionFilter));',
+      `  app.useGlobalFilters(app.get(CoreExceptionFilter));
+  setupSwagger(app, swaggerConfigService);`,
+    );
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchAppModule(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'app.module.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  if (!content.includes("from '@forgeon/swagger';")) {
+    if (content.includes("import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';")) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';",
+        "import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';",
+      );
+    } else if (
+      content.includes("import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';",
+        "import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';",
+      );
+    }
+  }
+
+  content = ensureLoadItem(content, 'swaggerConfig');
+  content = ensureValidatorSchema(content, 'swaggerEnvSchema');
+
+  content = ensureLineAfter(content, '    CoreErrorsModule,', '    ForgeonSwaggerModule,');
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchApiDockerfile(targetRoot) {
+  const dockerfilePath = path.join(targetRoot, 'apps', 'api', 'Dockerfile');
+  if (!fs.existsSync(dockerfilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(dockerfilePath, 'utf8').replace(/\r\n/g, '\n');
+
+  const packageAnchor = content.includes('COPY packages/logger/package.json packages/logger/package.json')
+    ? 'COPY packages/logger/package.json packages/logger/package.json'
+    : 'COPY packages/db-prisma/package.json packages/db-prisma/package.json';
+  content = ensureLineAfter(
+    content,
+    packageAnchor,
+    'COPY packages/swagger/package.json packages/swagger/package.json',
+  );
+
+  const sourceAnchor = content.includes('COPY packages/logger packages/logger')
+    ? 'COPY packages/logger packages/logger'
+    : 'COPY packages/db-prisma packages/db-prisma';
+  content = ensureLineAfter(content, sourceAnchor, 'COPY packages/swagger packages/swagger');
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/swagger build\r?\n?/gm, '');
+  content = ensureLineBefore(
+    content,
+    'RUN pnpm --filter @forgeon/api prisma:generate',
+    'RUN pnpm --filter @forgeon/swagger build',
+  );
+
+  fs.writeFileSync(dockerfilePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchCompose(targetRoot) {
+  const composePath = path.join(targetRoot, 'infra', 'docker', 'compose.yml');
+  if (!fs.existsSync(composePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(composePath, 'utf8').replace(/\r\n/g, '\n');
+  if (!content.includes('SWAGGER_ENABLED: ${SWAGGER_ENABLED}')) {
+    content = content.replace(
+      /^(\s+DATABASE_URL:.*)$/m,
+      `$1
+      SWAGGER_ENABLED: \${SWAGGER_ENABLED}
+      SWAGGER_PATH: \${SWAGGER_PATH}
+      SWAGGER_TITLE: \${SWAGGER_TITLE}
+      SWAGGER_VERSION: \${SWAGGER_VERSION}`,
+    );
+  }
+
+  fs.writeFileSync(composePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const marker = '## Swagger / OpenAPI Module';
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  if (content.includes(marker)) {
+    return;
+  }
+
+  const section = `## Swagger / OpenAPI Module
+
+The swagger add-module provides generated OpenAPI docs for the API.
+
+Configuration (env):
+- \`SWAGGER_ENABLED=false\`
+- \`SWAGGER_PATH=docs\`
+- \`SWAGGER_TITLE="Forgeon API"\`
+- \`SWAGGER_VERSION=1.0.0\`
+
+When enabled:
+- UI endpoint: \`http://localhost:3000/docs\` (or your configured path)
+- in Docker with proxy: \`http://localhost:8080/docs\`
+`;
+
+  if (content.includes('## Prisma In Docker Start')) {
+    content = content.replace('## Prisma In Docker Start', `${section}\n## Prisma In Docker Start`);
+  } else {
+    content = `${content.trimEnd()}\n\n${section}\n`;
+  }
+
+  fs.writeFileSync(readmePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+export function applySwaggerModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'swagger'));
+  patchApiPackage(targetRoot);
+  patchMain(targetRoot);
+  patchAppModule(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchCompose(targetRoot);
+  patchReadme(targetRoot);
+
+  upsertEnvLines(path.join(targetRoot, 'apps', 'api', '.env.example'), [
+    'SWAGGER_ENABLED=false',
+    'SWAGGER_PATH=docs',
+    'SWAGGER_TITLE="Forgeon API"',
+    'SWAGGER_VERSION=1.0.0',
+  ]);
+  upsertEnvLines(path.join(targetRoot, 'infra', 'docker', '.env.example'), [
+    'SWAGGER_ENABLED=false',
+    'SWAGGER_PATH=docs',
+    'SWAGGER_TITLE="Forgeon API"',
+    'SWAGGER_VERSION=1.0.0',
+  ]);
+}

package/templates/module-fragments/swagger/00_title.md

@@ -0,0 +1,6 @@
+# {{MODULE_LABEL}}
+
+- Id: `{{MODULE_ID}}`
+- Category: `{{MODULE_CATEGORY}}`
+- Status: {{MODULE_STATUS}}
+

package/templates/module-fragments/swagger/10_overview.md

@@ -0,0 +1,10 @@
+## Overview
+
+Adds OpenAPI docs support to the API.
+
+Included parts:
+- `@forgeon/swagger` package
+- env-driven toggle (`SWAGGER_ENABLED`)
+- configurable docs path/title/version
+- `setupSwagger(...)` bootstrap helper
+

package/templates/module-fragments/swagger/20_scope.md

@@ -0,0 +1,13 @@
+## Applied Scope
+
+- Adds `packages/swagger` workspace package
+- Wires swagger env schema into API config load/validation
+- Registers `ForgeonSwaggerModule` in API `AppModule`
+- Calls `setupSwagger(...)` from API bootstrap (`main.ts`)
+- Updates API package/deps/scripts for swagger package build
+- Updates API Docker build to include `@forgeon/swagger`
+- Adds swagger env keys to:
+  - `apps/api/.env.example`
+  - `infra/docker/.env.example`
+  - `infra/docker/compose.yml` (api service env passthrough)
+

package/templates/module-fragments/swagger/90_status_implemented.md

@@ -0,0 +1,4 @@
+## Status
+
+Implemented and applied by `create-forgeon add swagger`.
+

package/templates/module-presets/swagger/packages/swagger/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@forgeon/swagger",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/swagger": "^11.2.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}
+

package/templates/module-presets/swagger/packages/swagger/src/forgeon-swagger.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { SwaggerConfigModule } from './swagger-config.module';
+
+@Module({
+  imports: [SwaggerConfigModule],
+  exports: [SwaggerConfigModule],
+})
+export class ForgeonSwaggerModule {}
+

package/templates/module-presets/swagger/packages/swagger/src/index.ts

@@ -0,0 +1,7 @@
+export * from './swagger-env.schema';
+export * from './swagger-config.loader';
+export * from './swagger-config.service';
+export * from './swagger-config.module';
+export * from './forgeon-swagger.module';
+export * from './setup-swagger';
+

package/templates/module-presets/swagger/packages/swagger/src/setup-swagger.ts

@@ -0,0 +1,25 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { SwaggerConfigService } from './swagger-config.service';
+
+export function setupSwagger(app: INestApplication, config: SwaggerConfigService): void {
+  if (!config.enabled) {
+    return;
+  }
+
+  const document = SwaggerModule.createDocument(
+    app,
+    new DocumentBuilder()
+      .setTitle(config.title)
+      .setVersion(config.version)
+      .addBearerAuth()
+      .build(),
+  );
+
+  SwaggerModule.setup(config.path, app, document, {
+    swaggerOptions: {
+      persistAuthorization: true,
+    },
+  });
+}
+

package/templates/module-presets/swagger/packages/swagger/src/swagger-config.loader.ts

@@ -0,0 +1,22 @@
+import { registerAs } from '@nestjs/config';
+import { parseSwaggerEnv } from './swagger-env.schema';
+
+export const SWAGGER_CONFIG_NAMESPACE = 'swagger';
+
+export interface SwaggerConfigValues {
+  enabled: boolean;
+  path: string;
+  title: string;
+  version: string;
+}
+
+export const swaggerConfig = registerAs(SWAGGER_CONFIG_NAMESPACE, (): SwaggerConfigValues => {
+  const env = parseSwaggerEnv(process.env);
+  return {
+    enabled: env.SWAGGER_ENABLED,
+    path: env.SWAGGER_PATH.replace(/^\/+/, ''),
+    title: env.SWAGGER_TITLE,
+    version: env.SWAGGER_VERSION,
+  };
+});
+

package/templates/module-presets/swagger/packages/swagger/src/swagger-config.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { SwaggerConfigService } from './swagger-config.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [SwaggerConfigService],
+  exports: [SwaggerConfigService],
+})
+export class SwaggerConfigModule {}
+

package/templates/module-presets/swagger/packages/swagger/src/swagger-config.service.ts

@@ -0,0 +1,29 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SWAGGER_CONFIG_NAMESPACE, SwaggerConfigValues } from './swagger-config.loader';
+
+@Injectable()
+export class SwaggerConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get enabled(): boolean {
+    return this.configService.getOrThrow<boolean>(`${SWAGGER_CONFIG_NAMESPACE}.enabled`);
+  }
+
+  get path(): string {
+    return this.configService.getOrThrow<string>(`${SWAGGER_CONFIG_NAMESPACE}.path`);
+  }
+
+  get title(): string {
+    return this.configService.getOrThrow<SwaggerConfigValues['title']>(
+      `${SWAGGER_CONFIG_NAMESPACE}.title`,
+    );
+  }
+
+  get version(): string {
+    return this.configService.getOrThrow<SwaggerConfigValues['version']>(
+      `${SWAGGER_CONFIG_NAMESPACE}.version`,
+    );
+  }
+}
+

package/templates/module-presets/swagger/packages/swagger/src/swagger-env.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export const swaggerEnvSchema = z
+  .object({
+    SWAGGER_ENABLED: z.coerce.boolean().default(false),
+    SWAGGER_PATH: z.string().trim().min(1).default('docs'),
+    SWAGGER_TITLE: z.string().trim().min(1).default('Forgeon API'),
+    SWAGGER_VERSION: z.string().trim().min(1).default('1.0.0'),
+  })
+  .passthrough();
+
+export type SwaggerEnv = z.infer<typeof swaggerEnvSchema>;
+
+export function parseSwaggerEnv(input: Record<string, unknown>): SwaggerEnv {
+  return swaggerEnvSchema.parse(input);
+}
+

package/templates/module-presets/swagger/packages/swagger/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}
+