@pattern-stack/codegen 0.3.2 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -66,6 +66,7 @@
     "glob": "^13.0.6",
     "ora": "^9.3.0",
     "pluralize": "^8.0.0",
+    "ts-morph": "^28.0.0",
     "yaml": "^2.8.3",
     "zod": "^3.22.4"
   },
@@ -73,6 +74,7 @@
     "@cubejs-client/core": ">=1.0.0",
     "@nestjs/common": "^10",
     "@nestjs/core": "^10",
+    "@nestjs/swagger": "^7.0.0 || ^8.0.0",
     "bullmq": ">=5.0.0",
     "class-transformer": ">=0.5.0",
     "class-validator": ">=0.14.0",
@@ -82,9 +84,15 @@
     "rxjs": "^7.0.0"
   },
   "peerDependenciesMeta": {
+    "@anatine/zod-openapi": {
+      "optional": true
+    },
     "@cubejs-client/core": {
       "optional": true
     },
+    "@nestjs/swagger": {
+      "optional": true
+    },
     "bullmq": {
       "optional": true
     },
@@ -102,6 +110,7 @@
     "packages/*"
   ],
   "devDependencies": {
+    "@anatine/zod-openapi": "^2.2.8",
     "@cubejs-client/core": "^1.0.0",
     "@nestjs/common": "10",
     "@nestjs/core": "10",

package/templates/entity/new/backend/application/schemas/dto.ejs.t

@@ -43,3 +43,34 @@ export const update<%= className %>Schema = z.object({
 });
 
 export type Update<%= className %>Dto = z.infer<typeof update<%= className %>Schema>;
+
+// OPENAPI-3: response schema — mirrors the select shape of this entity so
+// controller `@ApiResponse({ schema: { $ref: '.../<%= className %>ResponseDto' } })`
+// decorators resolve to a fully-typed document on /docs-json.
+export const <%= camelName %>ResponseSchema = z.object({
+	id: z.string().uuid(),
+<% fields.forEach((field) => { -%>
+<% let zodChain = field.zodType; -%>
+<% if (field.type === 'string' && field.maxLength) { zodChain += `.max(${field.maxLength})`; } -%>
+<% if (field.type === 'string' && field.minLength) { zodChain += `.min(${field.minLength})`; } -%>
+<% if (['integer', 'decimal'].includes(field.type) && field.min !== undefined) { zodChain += `.min(${field.min})`; } -%>
+<% if (['integer', 'decimal'].includes(field.type) && field.max !== undefined) { zodChain += `.max(${field.max})`; } -%>
+<% if (field.choices) { zodChain = `z.enum([${field.choices.map(c => `'${c}'`).join(', ')}])`; } -%>
+<% if (field.nullable) { zodChain += '.nullable()'; } -%>
+	<%- field.camelName %>: <%- zodChain %>,
+<% }) -%>
+<% if (hasTimestamps) { -%>
+	createdAt: z.coerce.date(),
+	updatedAt: z.coerce.date(),
+<% } -%>
+<% if (hasSoftDelete) { -%>
+	deletedAt: z.coerce.date().nullable(),
+<% } -%>
+<% if (hasTemporalValidity) { -%>
+	validFrom: z.coerce.date().nullable(),
+	validTo: z.coerce.date().nullable(),
+	isActive: z.boolean(),
+<% } -%>
+});
+
+export type <%= className %>ResponseDto = z.infer<typeof <%= camelName %>ResponseSchema>;

package/templates/entity/new/backend/modules/core/module.ejs.t

@@ -14,7 +14,8 @@ force: true
 <% } -%>
  */
 
-import { Module } from '@nestjs/common';
+import { Inject, Module, type OnModuleInit } from '@nestjs/common';
+import { OPENAPI_REGISTRY, type OpenApiRegistry } from '@shared/openapi';
 import { <%= repositoryToken %> } from '<%= imports.moduleToConstants %>';
 import { <%= getByIdQueryClass %> } from '<%= imports.moduleToGetByIdQuery %>';
 <% if (!exposeElectric) { -%>
@@ -34,6 +35,9 @@ import { declarativeQueryClasses } from '<%= imports.moduleToDeclarativeQueries
 <% if (exposeRest || exposeElectric) { -%>
 import { <%= classNamePlural %>Controller } from '<%= imports.moduleToController %>';
 <% } -%>
+<% if (generate.dtos) { -%>
+import { create<%= className %>Schema, update<%= className %>Schema, <%= camelName %>ResponseSchema } from '<%= imports.moduleToDto %>';
+<% } -%>
 
 @Module({
 	imports: [DatabaseModule<%= exposeElectric ? ', ElectricModule' : '' %>],
@@ -70,4 +74,19 @@ import { <%= classNamePlural %>Controller } from '<%= imports.moduleToController
 <% } -%>
 	],
 })
-export class <%= classNamePlural %>Module {}
+export class <%= classNamePlural %>Module<% if (generate.dtos) { %> implements OnModuleInit<% } %> {
+<% if (generate.dtos) { -%>
+	// OPENAPI-2: register this entity's Zod schemas with the shared
+	// OpenApiRegistry at module init. OPENAPI-4 awaits `build()` at boot
+	// to emit the full /docs-json document.
+	constructor(
+		@Inject(OPENAPI_REGISTRY) private readonly openApi: OpenApiRegistry,
+	) {}
+
+	onModuleInit(): void {
+		this.openApi.registerSchema('Create<%= className %>Dto', create<%= className %>Schema);
+		this.openApi.registerSchema('Update<%= className %>Dto', update<%= className %>Schema);
+		this.openApi.registerSchema('<%= className %>ResponseDto', <%= camelName %>ResponseSchema);
+	}
+<% } -%>
+}

package/templates/entity/new/backend/presentation/controller.ejs.t

@@ -24,6 +24,13 @@ import {
 <% } -%>
 	UsePipes,
 } from '@nestjs/common';
+import {
+	ApiBearerAuth,
+	ApiBody,
+	ApiOperation,
+	ApiParam,
+	ApiResponse,
+} from '@nestjs/swagger';
 import { <%= getByIdQueryClass %> } from '<%= imports.controllerToGetByIdQuery %>';
 import { <%= listQueryClass %> } from '<%= imports.controllerToListQuery %>';
 import {
@@ -41,6 +48,13 @@ import { <%= className %> } from '<%= imports.controllerToDomain %>';
 import type { <%= className %>With } from '<%= imports.controllerToDomain %>';
 <% } -%>
 
+// OPENAPI-3: controller decorators reference schemas by `$ref` rather
+// than `type:` class references because generated DTOs are Zod-derived
+// types (not NestJS classes). Schemas are registered by name in the
+// `OpenApiRegistry` at onModuleInit (OPENAPI-2); these `$ref` URIs point
+// at those registered entries. `ErrorResponseDto` is auto-registered by
+// the shared registry.
+@ApiBearerAuth()
 @Controller('<%= plural %>')
 export class <%= classNamePlural %>Controller {
 	constructor(
@@ -51,6 +65,12 @@ export class <%= classNamePlural %>Controller {
 		private readonly delete<%= className %>Command: <%= deleteCommandClass %>,
 	) {}
 
+	@ApiOperation({ summary: 'List <%= plural %>', operationId: 'list<%= classNamePlural %>' })
+	@ApiResponse({
+		status: 200,
+		schema: { type: 'array', items: { $ref: '#/components/schemas/<%= className %>ResponseDto' } },
+	})
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
 	@Get()
 	async findAll(<%- hasRelationships ? `@Query('include') include?: string` : '' %>): Promise<<%= className %>[]> {
 <% if (hasRelationships) { -%>
@@ -60,6 +80,11 @@ export class <%= classNamePlural %>Controller {
 <% } -%>
 	}
 
+	@ApiOperation({ summary: 'Find <%= name %> by id', operationId: 'find<%= className %>ById' })
+	@ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Get(':id')
 	async findById(
 		@Param('id', ParseUUIDPipe) id: string,
@@ -74,6 +99,11 @@ export class <%= classNamePlural %>Controller {
 <% } -%>
 	}
 
+	@ApiOperation({ summary: 'Create <%= name %>', operationId: 'create<%= className %>' })
+	@ApiBody({ schema: { $ref: '#/components/schemas/Create<%= className %>Dto' } })
+	@ApiResponse({ status: 201, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
 	@Post()
 	@UsePipes(new ZodValidationPipe(create<%= className %>Schema))
 	async create(
@@ -84,6 +114,13 @@ export class <%= classNamePlural %>Controller {
 		return this.create<%= className %>Command.execute(dto, { actor: { tenantId, userId } });
 	}
 
+	@ApiOperation({ summary: 'Update <%= name %>', operationId: 'update<%= className %>' })
+	@ApiBody({ schema: { $ref: '#/components/schemas/Update<%= className %>Dto' } })
+	@ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Put(':id')
 	async update(
 		@Param('id', ParseUUIDPipe) id: string,
@@ -94,6 +131,11 @@ export class <%= classNamePlural %>Controller {
 		return this.update<%= className %>Command.execute(id, dto, { actor: { tenantId, userId } });
 	}
 
+	@ApiOperation({ summary: 'Delete <%= name %>', operationId: 'delete<%= className %>' })
+	@ApiResponse({ status: 204 })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Delete(':id')
 	async delete(
 		@Param('id', ParseUUIDPipe) id: string,
@@ -141,6 +183,13 @@ import {
 	UseGuards,
 	UsePipes,
 } from '@nestjs/common';
+import {
+	ApiBearerAuth,
+	ApiBody,
+	ApiOperation,
+	ApiParam,
+	ApiResponse,
+} from '@nestjs/swagger';
 import type { Request, Response } from 'express';
 import { AuthGuard } from '<%= imports.controllerToAuthGuard %>/auth.guard';
 import { CurrentUser } from '<%= imports.controllerToCurrentUser %>/current-user.decorator';
@@ -160,6 +209,7 @@ import { <%= getByIdQueryClass %> } from '<%= imports.controllerToGetByIdQuery %
 import { ZodValidationPipe } from '../../core/pipes/zod-validation.pipe';
 import { <%= className %> } from '<%= imports.controllerToDomain %>';
 
+@ApiBearerAuth()
 @Controller('<%= plural %>')
 @UseGuards(AuthGuard)
 export class <%= classNamePlural %>Controller {
@@ -171,6 +221,8 @@ export class <%= classNamePlural %>Controller {
 		private readonly delete<%= className %>Command: <%= deleteCommandClass %>,
 	) {}
 
+	@ApiOperation({ summary: 'List <%= plural %> (Electric SQL proxy)', operationId: 'list<%= classNamePlural %>' })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
 	@Get()
 	async findAll(
 		@CurrentUser() user: User,
@@ -186,11 +238,21 @@ export class <%= classNamePlural %>Controller {
 		});
 	}
 
+	@ApiOperation({ summary: 'Find <%= name %> by id', operationId: 'find<%= className %>ById' })
+	@ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Get(':id')
 	async findById(@Param('id', ParseUUIDPipe) id: string): Promise<<%= className %>> {
 		return this.get<%= className %>ByIdQuery.execute(id);
 	}
 
+	@ApiOperation({ summary: 'Create <%= name %>', operationId: 'create<%= className %>' })
+	@ApiBody({ schema: { $ref: '#/components/schemas/Create<%= className %>Dto' } })
+	@ApiResponse({ status: 201, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
 	@Post()
 	@UsePipes(new ZodValidationPipe(create<%= className %>Schema))
 	async create(
@@ -201,6 +263,13 @@ export class <%= classNamePlural %>Controller {
 		return this.create<%= className %>Command.execute(dto, { actor: { tenantId, userId } });
 	}
 
+	@ApiOperation({ summary: 'Update <%= name %>', operationId: 'update<%= className %>' })
+	@ApiBody({ schema: { $ref: '#/components/schemas/Update<%= className %>Dto' } })
+	@ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= className %>ResponseDto' } })
+	@ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Put(':id')
 	async update(
 		@Param('id', ParseUUIDPipe) id: string,
@@ -211,6 +280,11 @@ export class <%= classNamePlural %>Controller {
 		return this.update<%= className %>Command.execute(id, dto, { actor: { tenantId, userId } });
 	}
 
+	@ApiOperation({ summary: 'Delete <%= name %>', operationId: 'delete<%= className %>' })
+	@ApiResponse({ status: 204 })
+	@ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+	@ApiParam({ name: 'id', type: 'string', format: 'uuid' })
 	@Delete(':id')
 	async delete(
 		@Param('id', ParseUUIDPipe) id: string,

package/templates/entity/new/clean-lite-ps/controller.ejs.t

@@ -4,6 +4,7 @@ skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
 import { Controller, Get<% if (generateWrites) { %>, Post, Patch, Delete, Body, Headers<% } %>, NotFoundException, Param, ParseUUIDPipe } from '@nestjs/common';
+import { ApiBearerAuth, <% if (generateWrites) { %>ApiBody, <% } %>ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
 import { <%= classNames.findByIdUseCase %> } from './use-cases/find-<%= entityName %>-by-id.use-case';
 import { <%= classNames.listUseCase %> } from './use-cases/list-<%= entityNamePlural %>.use-case';
 <% if (eavEnabled) { -%>
@@ -22,6 +23,11 @@ import type { <%= classNames.updateDto %> } from './dto/update-<%= entityName %>
 <% } -%>
 import type { <%= classNames.entity %> } from './<%= entityName %>.entity';
 
+// OPENAPI-3: decorators reference registered schemas by `$ref` because
+// CLP DTOs are Zod-derived types (OPENAPI-2 registers them by name at
+// onModuleInit). `ErrorResponseDto` is auto-registered by the shared
+// registry.
+@ApiBearerAuth()
 @Controller('<%= entityNamePlural %>')
 export class <%= classNames.controller %> {
   constructor(
@@ -39,22 +45,47 @@ export class <%= classNames.controller %> {
 <% } -%>
   ) {}
 
+  @ApiOperation({ summary: 'List <%= entityNamePlural %>', operationId: 'list<%= classNames.entity %>s' })
+  @ApiResponse({
+    status: 200,
+    schema: { type: 'array', items: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } },
+  })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
   @Get()
   async getAll(): Promise<<%= classNames.entity %>[]> {
     return this.listUseCase.execute();
   }
 <% if (eavEnabled) { %>
+  @ApiOperation({
+    summary: 'List <%= entityNamePlural %> with EAV fields',
+    operationId: 'list<%= classNames.entity %>sWithFields',
+  })
+  @ApiResponse({ status: 200 })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
   @Get('with-fields')
   async getAllWithFields(): Promise<Array<<%= classNames.entity %> & { fields: Record<string, unknown> }>> {
     return this.listWithFieldsUseCase.execute();
   }
 <% } %>
+  @ApiOperation({ summary: 'Find <%= entityName %> by id', operationId: 'find<%= classNames.entity %>ById' })
+  @ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
   @Get(':id')
   async getById(@Param('id', ParseUUIDPipe) id: string): Promise<<%= classNames.entity %>> {
     // Use case throws NotFoundException on null/undefined (D2)
     return this.findByIdUseCase.execute(id);
   }
 <% if (eavEnabled) { %>
+  @ApiOperation({
+    summary: 'Find <%= entityName %> with EAV fields',
+    operationId: 'find<%= classNames.entity %>ByIdWithFields',
+  })
+  @ApiResponse({ status: 200 })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
   @Get(':id/with-fields')
   async getByIdWithFields(
     @Param('id', ParseUUIDPipe) id: string,
@@ -65,6 +96,11 @@ export class <%= classNames.controller %> {
   }
 <% } %>
 <% if (generateWrites) { %>
+  @ApiOperation({ summary: 'Create <%= entityName %>', operationId: 'create<%= classNames.entity %>' })
+  @ApiBody({ schema: { $ref: '#/components/schemas/<%= classNames.createDto %>' } })
+  @ApiResponse({ status: 201, schema: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } })
+  @ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
   @Post()
   async create(
     @Body(new ZodValidationPipe(<%= classNames.createSchema %>)) dto: <%= classNames.createDto %>,
@@ -74,6 +110,13 @@ export class <%= classNames.controller %> {
     return this.createUseCase.execute(dto, { actor: { tenantId, userId } });
   }
 
+  @ApiOperation({ summary: 'Update <%= entityName %>', operationId: 'update<%= classNames.entity %>' })
+  @ApiBody({ schema: { $ref: '#/components/schemas/<%= classNames.updateDto %>' } })
+  @ApiResponse({ status: 200, schema: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } })
+  @ApiResponse({ status: 400, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
   @Patch(':id')
   async update(
     @Param('id', ParseUUIDPipe) id: string,
@@ -86,6 +129,11 @@ export class <%= classNames.controller %> {
     return entity;
   }
 
+  @ApiOperation({ summary: 'Delete <%= entityName %>', operationId: 'delete<%= classNames.entity %>' })
+  @ApiResponse({ status: 204 })
+  @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiResponse({ status: 404, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
+  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
   @Delete(':id')
   async remove(
     @Param('id', ParseUUIDPipe) id: string,

package/templates/entity/new/clean-lite-ps/module.ejs.t

@@ -10,7 +10,8 @@ force: true
  * root AppModule (global) so these tokens resolve at runtime.
  */
 <% } -%>
-import { Module } from '@nestjs/common';
+import { Inject, Module, type OnModuleInit } from '@nestjs/common';
+import { OPENAPI_REGISTRY, type OpenApiRegistry } from '@shared/openapi';
 import { DatabaseModule } from '@shared/database/database.module';
 <%_ clpBelongsTo.forEach(rel => { _%>
 // import { <%= rel.relatedEntityPascal %>sModule } from '../<%= rel.relatedPlural %>/<%= rel.relatedPlural %>.module';
@@ -25,6 +26,10 @@ import { <%= eavDefinitionPluralPascal %>Module } from '../<%= eavDefinitionEnti
 import { <%= classNames.repository %> } from './<%= entityName %>.repository';
 import { <%= classNames.service %> } from './<%= entityName %>.service';
 import { <%= classNames.controller %> } from './<%= entityName %>.controller';
+// OPENAPI-2: Zod schemas registered with OpenApiRegistry at module init.
+import { <%= classNames.createSchema %> } from './dto/create-<%= entityName %>.dto';
+import { <%= classNames.updateSchema %> } from './dto/update-<%= entityName %>.dto';
+import { <%= classNames.outputSchema %> } from './dto/<%= entityName %>-output.dto';
 import { <%= classNames.findByIdUseCase %> } from './use-cases/find-<%= entityName %>-by-id.use-case';
 import { <%= classNames.listUseCase %> } from './use-cases/list-<%= entityNamePlural %>.use-case';
 <% if (eavEnabled) { -%>
@@ -83,4 +88,21 @@ import { <%= classNames.searchController %> } from './<%= entityName %>-search.c
   ],
   exports: [<%= classNames.service %>],  // Only service is exported (ADR-002)
 })
-export class <%= classNames.module %> {}
+export class <%= classNames.module %> implements OnModuleInit {
+  // OPENAPI-2: register this entity's Zod schemas with the shared
+  // OpenApiRegistry at module init. OPENAPI-4 awaits `build()` at boot
+  // to emit the full /docs-json document.
+  constructor(
+    @Inject(OPENAPI_REGISTRY) private readonly openApi: OpenApiRegistry,
+  ) {}
+
+  onModuleInit(): void {
+    this.openApi.registerSchema('<%= classNames.createDto %>', <%= classNames.createSchema %>);
+    this.openApi.registerSchema('<%= classNames.updateDto %>', <%= classNames.updateSchema %>);
+    // CLP pipeline names the response schema <Entity>OutputDto (matches
+    // classNames.outputDto); the OPENAPI-2 spec sketch uses "ResponseDto"
+    // but existing CLP code already publishes OutputDto everywhere, so we
+    // keep consistency. OPENAPI-3 decorators reference the same name.
+    this.openApi.registerSchema('<%= classNames.outputDto %>', <%= classNames.outputSchema %>);
+  }
+}

package/templates/entity/new/prompt.js

@@ -575,6 +575,8 @@ export default {
       moduleToConstants: importHelpers.moduleToConstants(),
       moduleToDatabaseModule: importHelpers.moduleToDatabaseModule(),
       moduleToController: importHelpers.moduleToController(fileNames.controller.replace('.ts', '')),
+      // OPENAPI-2: module imports DTO file to register Zod schemas at onModuleInit.
+      moduleToDto: importHelpers.moduleToDto(fileNames.dto.replace('.ts', '')),
       // From controller (presentation/rest/) to queries/commands
       controllerToGetByIdQuery: importHelpers.controllerToQuery(name, fileNames.getByIdQuery.replace('.ts', '')),
       controllerToListQuery: importHelpers.controllerToQuery(name, fileNames.listQuery.replace('.ts', '')),

package/templates/subsystem/openapi-config/codegen-config-openapi-block.ejs.t

@@ -0,0 +1,35 @@
+---
+to: "<%= configPath %>"
+inject: true
+append: true
+skip_if: "openapi:"
+---
+
+openapi:
+  # ── Master switch (OPENAPI-4) ──
+  # When false the `main.ts` bootstrap skips Swagger setup entirely — no
+  # `/docs` route, no `/docs-json`, no BearerAuth scheme. Generated
+  # controllers still emit `@nestjs/swagger` decorators (see gotchas in
+  # CONSUMER-SETUP §OpenAPI) so you must keep the peer dep installed
+  # either way.
+  enabled: true
+
+  # ── Mount point for Swagger UI (+ the JSON spec at `<path>-json`) ──
+  # '/docs' is the locked default; any path works. Conventional
+  # alternatives: '/api-docs', '/openapi', '/swagger'.
+  path: /docs
+
+  # ── Document metadata rendered in Swagger UI ──
+  # `title` appears as the page heading; `version` in the header badge.
+  # `description` is the paragraph beneath the title.
+  title: My App
+  version: 0.1.0
+  description: Generated by @pattern-stack/codegen
+
+  # ── Default security scheme ──
+  # 'bearer' registers `components.securitySchemes.bearer` as
+  # `{ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }` and applies
+  # it globally via `document.security = [{ bearer: [] }]`. Controllers
+  # already emit `@ApiBearerAuth()` at the class level (OPENAPI-3), so
+  # Swagger UI's "Authorize" button renders out of the box.
+  auth: bearer

package/templates/subsystem/openapi-config/prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Hygen prompt.js — OPENAPI-4 OpenAPI config-block scaffold.
+ *
+ * The OpenAPI "subsystem" is config-only: the runtime helpers
+ * (`OpenApiRegistry`, `OPENAPI_REGISTRY` token, `ErrorResponseDto`) are
+ * already vendored into every consumer project by `codegen project init`
+ * (see `src/cli/shared/init-scaffold.ts::VENDORED_RUNTIME_FILES`). So
+ * there is no `runtime/subsystems/openapi/` directory to copy — this
+ * template's sole job is to inject the `openapi:` block into
+ * `codegen.config.yaml`.
+ *
+ * Mirrors the bridge-config / events-config / jobs-config / sync-config
+ * prompt.js shape. Invoked via:
+ *   bunx hygen subsystem openapi-config --configPath <abs>
+ */
+
+export default {
+  prompt: async ({ args }) => {
+    return {
+      configPath: args.configPath ?? "codegen.config.yaml",
+    };
+  },
+};