nestjs-docfy 0.2.6 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,49 +1,71 @@
1
- # nestjs-docfy
1
+ <p align="center">
2
+ <a href="http://nestjs.com"><img alt="Nest Logo" src="https://nestjs.com/img/logo-small.svg" width="120"></a>
3
+ </p>
4
+
5
+ <h1 align="center">
6
+ nestjs-docfy
7
+ </h1>
8
+
9
+ [![NPM version](https://img.shields.io/npm/v/nestjs-docfy.svg)](https://www.npmjs.com/package/nestjs-docfy)
10
+ [![NPM downloads](https://img.shields.io/npm/dw/nestjs-docfy.svg)](https://www.npmjs.com/package/nestjs-docfy)
11
+ [![GitHub last commit](https://img.shields.io/github/last-commit/MarvinRF/nest-docfy)](https://github.com/MarvinRF/nest-docfy/commits/main)
12
+ [![GitHub issues](https://img.shields.io/github/issues/MarvinRF/nest-docfy.svg)](https://github.com/MarvinRF/nest-docfy/issues)
13
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/MarvinRF/nest-docfy/blob/main/LICENSE)
2
14
 
3
15
  Keep your NestJS controllers clean. Swagger documentation lives in a dedicated companion file — by naming convention, zero boilerplate.
4
16
 
5
- ## Before / After
17
+ ## Table of contents
18
+
19
+ - [Motivation](#motivation)
20
+ - [Installation](#installation)
21
+ - [Quick start](#quick-start)
22
+ - [1. Import DocfyModule](#1-import-docfymodule)
23
+ - [2. Mark your controllers](#2-mark-your-controllers)
24
+ - [3. Generate companion docs files](#3-generate-companion-docs-files)
25
+ - [4. Fill in the docs file](#4-fill-in-the-docs-file)
26
+ - [CLI — generate](#cli--generate)
27
+ - [Options](#options)
28
+ - [Project types](#project-types)
29
+ - [Idempotency and --force](#idempotency-and---force)
30
+ - [CLI — check](#cli--check)
31
+ - [API reference](#api-reference)
32
+ - [DocfyModule.forRoot()](#docfymoduleforrootoptions)
33
+ - [@WithDocs()](#withdocs)
34
+ - [docs()](#docscontrollerclass-config)
35
+ - [Interface-typed DTOs](#interface-typed-dtos)
36
+ - [class-validator inference](#class-validator-inference)
37
+ - [@HttpCode() support](#httpcode-support)
38
+ - [File naming convention](#file-naming-convention)
39
+ - [Testing](#testing)
40
+ - [How it works](#how-it-works)
41
+ - [License](#license)
42
+
43
+ ## Motivation
44
+
45
+ Swagger decorators are documentation. They have nothing to do with routing logic, validation, or business rules — yet they end up mixed into the same file, doubling its length and burying the code that actually matters.
6
46
 
7
- **Before** — Swagger decorators buried in your controller:
47
+ **Before** — Swagger decorators scattered across your controller:
8
48
 
9
49
  ```ts
10
50
  // users.controller.ts
11
- @ApiTags('users')
12
- @Controller('users')
51
+ @ApiTags("users")
52
+ @Controller("users")
13
53
  export class UsersController {
14
54
  @Get()
15
- @ApiOperation({ summary: 'List all users' })
16
- @ApiResponse({ status: 200, type: [UserEntity] })
55
+ @ApiOperation({ summary: "List all users" })
56
+ @ApiResponse({ status: 200, description: "OK", type: [UserEntity] })
17
57
  findAll(): Promise<UserEntity[]> {
18
58
  return this.usersService.findAll();
19
59
  }
20
60
 
21
- @Get(':id')
22
- @ApiOperation({ summary: 'Get a user by ID' })
23
- @ApiParam({ name: 'id', description: 'User UUID' })
24
- @ApiResponse({ status: 200, type: UserEntity })
25
- @ApiResponse({ status: 404, description: 'User not found' })
26
- findOne(@Param('id') id: string): Promise<UserEntity> {
27
- return this.usersService.findOne(id);
28
- }
29
-
30
61
  @Post()
31
- @ApiOperation({ summary: 'Create a user' })
62
+ @ApiOperation({ summary: "Create a user" })
32
63
  @ApiBody({ type: CreateUserDto })
33
- @ApiResponse({ status: 201, type: UserEntity })
34
- @ApiResponse({ status: 400, description: 'Invalid input' })
64
+ @ApiResponse({ status: 201, description: "Created", type: UserEntity })
65
+ @ApiResponse({ status: 400, description: "Bad Request" })
35
66
  create(@Body() dto: CreateUserDto): Promise<UserEntity> {
36
67
  return this.usersService.create(dto);
37
68
  }
38
-
39
- @Delete(':id')
40
- @ApiOperation({ summary: 'Delete a user' })
41
- @ApiParam({ name: 'id', description: 'User UUID' })
42
- @ApiResponse({ status: 204 })
43
- @ApiResponse({ status: 404, description: 'User not found' })
44
- remove(@Param('id') id: string): Promise<void> {
45
- return this.usersService.remove(id);
46
- }
47
69
  }
48
70
  ```
49
71
 
@@ -52,49 +74,37 @@ export class UsersController {
52
74
  ```ts
53
75
  // users.controller.ts
54
76
  @WithDocs()
55
- @Controller('users')
77
+ @Controller("users")
56
78
  export class UsersController {
57
79
  findAll(): Promise<UserEntity[]> {
58
80
  return this.usersService.findAll();
59
81
  }
60
82
 
61
- findOne(@Param('id') id: string): Promise<UserEntity> {
62
- return this.usersService.findOne(id);
63
- }
64
-
65
83
  create(@Body() dto: CreateUserDto): Promise<UserEntity> {
66
84
  return this.usersService.create(dto);
67
85
  }
68
-
69
- remove(@Param('id') id: string): Promise<void> {
70
- return this.usersService.remove(id);
71
- }
72
86
  }
73
87
  ```
74
88
 
75
89
  ```ts
76
90
  // users.controller.docs.ts — all documentation in one place
77
91
  docs(UsersController, {
78
- classDecorators: [ApiTags('users')],
92
+ classDecorators: [ApiTags("users")],
79
93
  methods: {
80
94
  findAll: [
81
- ApiOperation({ summary: 'List all users' }),
82
- ApiResponse({ status: 200, type: [UserEntity] }),
95
+ ApiOperation({ summary: "List all users" }),
96
+ ApiResponse({ status: 200, description: "OK", type: [UserEntity] }),
83
97
  ],
84
98
  create: [
85
- ApiOperation({ summary: 'Create a user' }),
99
+ ApiOperation({ summary: "Create a user" }),
86
100
  ApiBody({ type: CreateUserDto }),
87
- ApiResponse({ status: 201, type: UserEntity }),
88
- ApiResponse({ status: 400, description: 'Invalid input' }),
101
+ ApiResponse({ status: 201, description: "Created", type: UserEntity }),
102
+ ApiResponse({ status: 400, description: "Bad Request" }),
89
103
  ],
90
104
  },
91
105
  });
92
106
  ```
93
107
 
94
- ## Why
95
-
96
- Swagger decorators are documentation. They have nothing to do with routing logic, validation, or business rules — yet they end up mixed into the same file, doubling its length and burying the code that actually matters.
97
-
98
108
  `nestjs-docfy` enforces a clean boundary: controllers express behavior, docs files express documentation. The convention (`*.controller.docs.ts`) mirrors how NestJS already organizes specs (`*.controller.spec.ts`), so it feels natural from day one.
99
109
 
100
110
  ## Installation
@@ -103,46 +113,48 @@ Swagger decorators are documentation. They have nothing to do with routing logic
103
113
  npm install nestjs-docfy
104
114
  ```
105
115
 
106
- **Peer dependencies** (already in your project):
116
+ **Peer dependencies** (already present in any NestJS project):
107
117
 
108
118
  ```bash
109
119
  npm install @nestjs/common @nestjs/swagger reflect-metadata
110
120
  ```
111
121
 
112
- ## Setup
122
+ ## Quick start
113
123
 
114
- ### 1. Import `DocfyModule` in your root module
124
+ ### 1. Import DocfyModule
115
125
 
116
126
  ```ts
117
127
  // app.module.ts
118
- import { Module } from '@nestjs/common';
119
- import { DocfyModule } from 'nestjs-docfy';
120
- import { UsersModule } from './users/users.module';
128
+ import { Module } from "@nestjs/common";
129
+ import { DocfyModule } from "nestjs-docfy";
121
130
 
122
131
  @Module({
123
- imports: [
124
- DocfyModule.forRoot(),
125
- UsersModule,
126
- ],
132
+ imports: [DocfyModule.forRoot()],
127
133
  })
128
134
  export class AppModule {}
129
135
  ```
130
136
 
131
- ### 2. Mark your controllers with `@WithDocs()`
137
+ Pass `{ strict: true }` to fail fast at startup when a controller has `@WithDocs()` but no companion file is found — recommended for CI:
138
+
139
+ ```ts
140
+ DocfyModule.forRoot({ strict: true });
141
+ ```
142
+
143
+ ### 2. Mark your controllers
132
144
 
133
145
  ```ts
134
146
  // users.controller.ts
135
- import { Controller, Get, Post, Body, Param, Delete } from '@nestjs/common';
136
- import { WithDocs } from 'nestjs-docfy';
147
+ import { Controller, Get, Post, Body } from "@nestjs/common";
148
+ import { WithDocs } from "nestjs-docfy";
137
149
 
138
150
  @WithDocs()
139
- @Controller('users')
151
+ @Controller("users")
140
152
  export class UsersController {
141
- // ... your route handlers, nothing else
153
+ // route handlers only — no Swagger decorators here
142
154
  }
143
155
  ```
144
156
 
145
- ### 3. Generate the companion docs files
157
+ ### 3. Generate companion docs files
146
158
 
147
159
  Run the CLI to scan your project and generate a pre-filled `*.controller.docs.ts` for every controller:
148
160
 
@@ -150,72 +162,54 @@ Run the CLI to scan your project and generate a pre-filled `*.controller.docs.ts
150
162
  npx nestjs-docfy generate
151
163
  ```
152
164
 
153
- This produces files like:
165
+ The CLI uses **static analysis only** (no code execution) and auto-detects your project layout — monorepos, Nx workspaces, and Nest CLI monorepos are all supported.
166
+
167
+ To preview what would be written without touching the filesystem:
168
+
169
+ ```bash
170
+ npx nestjs-docfy generate --dry-run
171
+ ```
172
+
173
+ ### 4. Fill in the docs file
174
+
175
+ The generated file comes pre-populated with inferred summaries, response types, and common error responses:
154
176
 
155
177
  ```ts
156
- // users.controller.docs.ts (generated — fill in the arrays)
157
- import { docs } from 'nestjs-docfy';
158
- import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
159
- import { UsersController } from './users.controller';
178
+ // Generated by nestjs-docfy — edit freely, use --force to merge new methods
179
+ import { docs } from "nestjs-docfy";
180
+ import { ApiTags, ApiOperation, ApiResponse, ApiBody } from "@nestjs/swagger";
181
+ import { UsersController } from "./users.controller";
182
+ import { CreateUserDto } from "./dto/create-user.dto";
183
+ import { UserEntity } from "./entities/user.entity";
160
184
 
161
185
  docs(UsersController, {
162
- classDecorators: [
163
- // ApiTags('users'),
164
- ],
186
+ classDecorators: [ApiTags("users")],
165
187
  methods: {
166
- // GET /users → async findAll(): Promise<UserEntity[]>
188
+ // GET / → async findAll(): Promise<UserEntity[]>
167
189
  findAll: [
168
- // ApiOperation({ summary: '' }),
169
- // ApiResponse({ status: 200, type: [UserEntity] }),
190
+ ApiOperation({ summary: "Find all" }),
191
+ ApiResponse({ status: 200, description: "OK", type: [UserEntity] }),
170
192
  ],
171
193
 
172
- // GET /:id → async findOne(id: string): Promise<UserEntity>
173
- findOne: [
174
- // ApiOperation({ summary: '' }),
175
- // ApiResponse({ status: 200, type: UserEntity }),
176
- // ApiResponse({ status: 404 }),
194
+ // POST / → async create(dto: CreateUserDto): Promise<UserEntity>
195
+ create: [
196
+ ApiOperation({ summary: "Create" }),
197
+ ApiBody({ type: CreateUserDto }),
198
+ ApiResponse({ status: 201, description: "Created", type: UserEntity }),
199
+ ApiResponse({ status: 400, description: "Bad Request" }),
177
200
  ],
178
201
  },
179
202
  });
180
203
  ```
181
204
 
182
- Or create the file manually following the same convention:
183
-
184
- ```text
185
- src/users/users.controller.ts ← your controller
186
- src/users/users.controller.docs.ts ← documentation goes here
187
- ```
188
-
189
- ### 4. Keep `main.ts` unchanged
190
-
191
- `DocfyModule` applies documentation metadata synchronously during module initialization, before `SwaggerModule.createDocument` is called. No changes to your bootstrap function are needed.
192
-
193
- ```ts
194
- // main.ts — nothing changes here
195
- async function bootstrap() {
196
- const app = await NestFactory.create(AppModule);
197
- const config = new DocumentBuilder().setTitle('My API').build();
198
- const document = SwaggerModule.createDocument(app, config);
199
- SwaggerModule.setup('api', app, document);
200
- await app.listen(3000);
201
- }
202
- ```
203
-
204
- ## CLI — `nestjs-docfy generate`
205
+ Edit the file freely — your changes are safe. Running `generate` again will skip existing files. Use `--force` to merge only **new** methods without touching existing ones.
205
206
 
206
- Scans your project for NestJS controllers using **static analysis only** (no code execution) and generates companion `*.controller.docs.ts` files with every method pre-filled and ready to annotate.
207
+ No changes to `main.ts` are needed. `DocfyModule` applies all metadata before `SwaggerModule.createDocument()` is called.
207
208
 
208
- ### Basic usage
209
+ ## CLI — generate
209
210
 
210
211
  ```bash
211
- # Auto-detect project type and generate all docs files
212
- npx nestjs-docfy generate
213
-
214
- # Preview what would be generated without writing anything
215
- npx nestjs-docfy generate --dry-run
216
-
217
- # Add new methods to existing docs files without touching decorated ones
218
- npx nestjs-docfy generate --force
212
+ npx nestjs-docfy generate [options]
219
213
  ```
220
214
 
221
215
  ### Options
@@ -231,58 +225,94 @@ npx nestjs-docfy generate --force
231
225
  | `--quiet` | `false` | Suppress all output except errors (CI-friendly) |
232
226
  | `--format` | `ts` | Output format: `ts` or `js` |
233
227
 
234
- ### Project types supported
228
+ ### Project types
235
229
 
236
230
  The CLI auto-detects your project layout — no configuration needed:
237
231
 
238
- | Layout | Detected when |
239
- | ----------------- | ------------------------------------------------------ |
240
- | Simple project | `tsconfig.json` at root, no monorepo markers |
241
- | NX Monorepo | `nx.json` present |
242
- | Nest CLI Monorepo | `nest-cli.json` with `"monorepo": true` |
243
- | Generic Monorepo | `packages/` or `apps/` with sub-`package.json` files |
232
+ | Layout | Detected when |
233
+ | ----------------- | ---------------------------------------------------- |
234
+ | Simple project | `tsconfig.json` at root, no monorepo markers |
235
+ | Nx monorepo | `nx.json` present |
236
+ | Nest CLI monorepo | `nest-cli.json` with `"monorepo": true` |
237
+ | Generic monorepo | `packages/` or `apps/` with sub-`package.json` files |
244
238
 
245
- ### Recommended script
239
+ ### Idempotency and --force
246
240
 
247
- Add to your `package.json`:
241
+ | Scenario | Behavior |
242
+ | ------------------------------------------ | -------------------------------------------------- |
243
+ | Run `generate` on a clean project | Creates all docs files |
244
+ | Run `generate` again (no changes) | Skips all existing files — safe to run repeatedly |
245
+ | Add a new endpoint, run `generate --force` | Merges new method block, preserves existing arrays |
246
+ | Edit a method's decorators, run `--force` | Your edits are preserved |
247
+
248
+ Add to your `package.json` for convenience:
248
249
 
249
250
  ```json
250
- "scripts": {
251
- "docs:generate": "nestjs-docfy generate"
251
+ {
252
+ "scripts": {
253
+ "docs:generate": "nestjs-docfy generate",
254
+ "docs:preview": "nestjs-docfy generate --dry-run"
255
+ }
252
256
  }
253
257
  ```
254
258
 
255
- Then run:
259
+ ## CLI — check
260
+
261
+ Verify that every controller is fully documented before merging. Exits with code `1` if any drift is detected — designed for CI pipelines.
256
262
 
257
263
  ```bash
258
- npm run docs:generate
264
+ npx nestjs-docfy check [options]
259
265
  ```
260
266
 
261
- ### Idempotency and `--force`
267
+ | Option | Default | Description |
268
+ | ------------------- | ------------------------- | ------------------------------------------- |
269
+ | `--root <path>` | `.` | Project root directory |
270
+ | `--tsconfig <path>` | auto-detected | Path to `tsconfig.json` |
271
+ | `--pattern <glob>` | `**/*.controller.ts` | Glob pattern to find controllers |
272
+ | `--format <format>` | `ts` | Docs file format to look for: `ts` or `js` |
273
+ | `--quiet` | `false` | Suppress all output except errors |
262
274
 
263
- Without `--force`: running `generate` twice is safe — existing docs files are skipped entirely.
275
+ **What it checks:**
264
276
 
265
- With `--force`: the CLI merges only **new** methods (methods added to the controller since the docs file was last generated). User-edited decorator arrays are preserved. This makes `--force` safe to run after adding endpoints.
277
+ - Controllers with HTTP methods but no companion docs file
278
+ - Controllers that have methods added since the last `generate` run
266
279
 
267
- ## API reference
280
+ **Example output:**
268
281
 
269
- ### `DocfyModule.forRoot(options?)`
282
+ ```text
283
+ ✖ UsersController — undocumented methods: updateProfile, deleteAccount
284
+ → run nestjs-docfy generate --force to merge new methods
270
285
 
271
- Registers the module and loads all companion docs files for controllers marked with `@WithDocs()`.
286
+ ✖ 2 controller(s) out of sync.
287
+ ```
272
288
 
273
- | Option | Type | Default | Description |
274
- | -------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------- |
275
- | `strict` | `boolean` | `false` | Throw at startup if a controller has `@WithDocs()` but no companion docs file is found. Recommended for CI. |
289
+ **CI integration:**
276
290
 
277
- ```ts
278
- // Warn on missing docs files (default)
279
- DocfyModule.forRoot()
291
+ ```yaml
292
+ # GitHub Actions example
293
+ - name: Check docs are up to date
294
+ run: npx nestjs-docfy check
295
+ ```
296
+
297
+ Or as an npm script:
280
298
 
281
- // Throw on missing docs files — fail fast in CI
282
- DocfyModule.forRoot({ strict: true })
299
+ ```json
300
+ {
301
+ "scripts": {
302
+ "docs:check": "nestjs-docfy check"
303
+ }
304
+ }
283
305
  ```
284
306
 
285
- ---
307
+ ## API reference
308
+
309
+ ### `DocfyModule.forRoot(options?)`
310
+
311
+ Registers the module and loads all companion docs files for controllers marked with `@WithDocs()`.
312
+
313
+ | Option | Type | Default | Description |
314
+ | -------- | --------- | ------- | ---------------------------------------------------------------------------------------------- |
315
+ | `strict` | `boolean` | `false` | Throw at startup if a `@WithDocs()` controller has no companion docs file. Recommended for CI. |
286
316
 
287
317
  ### `@WithDocs()`
288
318
 
@@ -294,70 +324,160 @@ Class decorator that marks a controller for companion file discovery. Pair with
294
324
  export class ProductsController { ... }
295
325
  ```
296
326
 
297
- Also sets `DOCFY_MARKER` metadata (`'docfy:with_docs'`) on the class, available for external introspection:
327
+ Also sets `DOCFY_MARKER` metadata on the class, available for external introspection:
298
328
 
299
329
  ```ts
300
- import { DOCFY_MARKER } from 'nestjs-docfy';
330
+ import { DOCFY_MARKER } from "nestjs-docfy";
301
331
 
302
- const hasDocs = Reflect.getMetadata(DOCFY_MARKER, ProductsController) === true;
332
+ Reflect.getMetadata(DOCFY_MARKER, ProductsController); // true
303
333
  ```
304
334
 
305
- ---
306
-
307
335
  ### `docs(controllerClass, config)`
308
336
 
309
- Applies Swagger decorators to a controller class from outside its file.
310
- Call this at the top level of a `*.controller.docs.ts` file — it runs as a side effect on import.
337
+ Applies Swagger decorators to a controller class from outside its file. Call at the top level of a `*.controller.docs.ts` file — runs as a side effect on import.
311
338
 
312
- The function is fully type-safe: `config.methods` only accepts keys that exist on the controller class. Typos are caught at compile time.
339
+ Fully type-safe: `config.methods` only accepts keys that exist on the controller class. Typos are caught at compile time.
313
340
 
314
341
  ```ts
315
342
  docs(UsersController, {
316
343
  classDecorators: [ApiTags('users')],
317
344
  methods: {
318
- findAll: [...], // ✔ exists on UsersController
319
- typoMethod: [...] // ✖ TypeScript error
345
+ findAll: [...], // ✔ exists on UsersController
346
+ typoMethod: [...], // ✖ TypeScript error
320
347
  },
321
348
  });
322
349
  ```
323
350
 
324
- **`config.classDecorators`** — `ClassDecorator[]` — decorators applied to the class constructor (e.g. `ApiTags`).
351
+ **`config.classDecorators`** — `ClassDecorator[]` — applied to the class constructor (e.g. `ApiTags`, `ApiBearerAuth`).
352
+
353
+ **`config.methods`** — `Partial<Record<keyof T, MethodDecorator[]>>` — decorator arrays per method name, applied in order.
354
+
355
+ If a method key does not exist on the controller at runtime, a warning is logged and that entry is skipped — the rest of the docs file still applies.
356
+
357
+ ## Interface-typed DTOs
358
+
359
+ When a response or body type is a TypeScript `interface` (not a class), Swagger cannot use it as a `type:` value because interfaces are erased at runtime. `nestjs-docfy` detects this automatically and generates an inline `schema:` object instead — **no changes to your code required**.
360
+
361
+ ```ts
362
+ // Your existing interface — no need to convert to a class
363
+ export interface RegisterResponseDto {
364
+ success: boolean;
365
+ message: string | null;
366
+ }
367
+ ```
368
+
369
+ Generated output:
370
+
371
+ ```ts
372
+ ApiResponse({
373
+ status: 201,
374
+ description: 'Created',
375
+ schema: {
376
+ type: 'object',
377
+ properties: {
378
+ success: { type: 'boolean' },
379
+ message: { type: 'string', nullable: true },
380
+ },
381
+ required: ['success'],
382
+ },
383
+ }),
384
+ ```
385
+
386
+ Supports: primitives, nullable unions (`T | null`), arrays, nested interfaces, and optional properties (excluded from `required`).
325
387
 
326
- **`config.methods`** — `Partial<Record<keyof T, MethodDecorator[]>>` — decorators per method name. Each decorator is called exactly as TypeScript would call it if it were written inline.
388
+ ## class-validator inference
327
389
 
328
- If a method name in `config.methods` does not exist on the controller at runtime, a warning is logged and that entry is skipped — the rest of the docs file still applies.
390
+ When a DTO class uses `class-validator` decorators and does **not** already have `@ApiProperty` on its properties, `nestjs-docfy` infers a full JSON Schema from the validator decorators — no manual annotation required.
391
+
392
+ ```ts
393
+ // create-user.dto.ts
394
+ import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';
395
+
396
+ export class CreateUserDto {
397
+ @IsString()
398
+ @MinLength(2)
399
+ name: string;
400
+
401
+ @IsEmail()
402
+ email: string;
403
+
404
+ @IsOptional()
405
+ @IsString()
406
+ bio?: string;
407
+ }
408
+ ```
409
+
410
+ Generated output:
411
+
412
+ ```ts
413
+ ApiBody({
414
+ schema: {
415
+ type: 'object',
416
+ properties: {
417
+ name: { type: 'string', minLength: 2 },
418
+ email: { type: 'string', format: 'email' },
419
+ bio: { type: 'string' },
420
+ },
421
+ required: ['name', 'email'],
422
+ },
423
+ }),
424
+ ```
425
+
426
+ Supported decorators: `@IsString`, `@IsEmail`, `@IsUrl`, `@IsUUID`, `@IsDateString`, `@IsNumber`, `@IsInt`, `@IsBoolean`, `@IsArray`, `@Min`, `@Max`, `@MinLength`, `@MaxLength`, `@IsOptional`.
427
+
428
+ > If any property in the class already has `@ApiProperty`, inference is skipped and `type: ClassName` is used instead — your existing Swagger annotations are never overwritten.
429
+
430
+ ## @HttpCode() support
431
+
432
+ NestJS's `@HttpCode()` decorator overrides the default HTTP status code for a route handler. `nestjs-docfy` reads it automatically and uses the correct code in the generated `ApiResponse`.
433
+
434
+ ```ts
435
+ // users.controller.ts
436
+ @Post('logout')
437
+ @HttpCode(204)
438
+ logout(): void { ... }
439
+ ```
440
+
441
+ Generated output:
442
+
443
+ ```ts
444
+ logout: [
445
+ ApiOperation({ summary: 'Logout' }),
446
+ ApiResponse({ status: 204, description: 'No Content' }),
447
+ ],
448
+ ```
449
+
450
+ Without `@HttpCode()`, the default codes apply: `201` for `@Post`, `200` for all other HTTP verbs.
329
451
 
330
452
  ## File naming convention
331
453
 
332
- | Controller file | Companion docs file |
333
- | --------------------------------- | ---------------------------- |
334
- | `users.controller.ts` | `users.controller.docs.ts` |
335
- | `users.controller.js` (compiled) | `users.controller.docs.js` |
454
+ Discovery is automatic. `DocfyModule` locates each controller's source file via Node's module cache and resolves the companion path — this works identically in `ts-node` (development) and compiled `dist/` (production).
336
455
 
337
- Discovery is automatic. `DocfyModule` locates each controller's source file via Node's module cache (`require.cache`) and resolves the companion path. This works identically in both `ts-node` (development) and compiled `dist/` (production).
456
+ | Controller file | Companion docs file |
457
+ | --------------------- | -------------------------- |
458
+ | `users.controller.ts` | `users.controller.docs.ts` |
459
+ | `users.controller.js` | `users.controller.docs.js` |
338
460
 
339
- > **Barrel re-exports**: if your controller is exported from an `index.ts` barrel in addition to its own file, `nestjs-docfy` prefers the `.controller.ts` file over the barrel. Make sure the class is exported directly from its own module file.
461
+ > **Barrel re-exports**: if your controller is also exported from an `index.ts` barrel, make sure the class is exported directly from its own module file. `nestjs-docfy` prefers `.controller.ts` over barrel files.
340
462
 
341
463
  ## Testing
342
464
 
343
- When testing application modules that import `DocfyModule`, reset the controller registry between test suites to avoid cross-contamination:
465
+ Reset the controller registry between test suites to avoid cross-contamination:
344
466
 
345
467
  ```ts
346
- import { resetDocfyRegistry } from 'nestjs-docfy/testing';
468
+ import { resetDocfyRegistry } from "nestjs-docfy/testing";
347
469
 
348
470
  beforeEach(() => resetDocfyRegistry());
349
471
  ```
350
472
 
351
473
  ## How it works
352
474
 
353
- NestJS calls `NestFactory.create()` to build the dependency graph and module instances, then calls `app.listen()` — which internally calls `app.init()` — to register routes and fire lifecycle hooks. `SwaggerModule.createDocument()` is called between these two steps, in `main.ts`.
354
-
355
- `DocfyModule.forRoot()` runs synchronously during the `NestFactory.create()` phase (as the module graph is evaluated), which is *before* `SwaggerModule.createDocument()`. At that point, it uses `require()` to load each docs file, which calls `docs()` and writes `Reflect` metadata directly onto the controller methods — exactly as TypeScript decorator syntax would at class-definition time.
475
+ `DocfyModule.forRoot()` runs synchronously during the `NestFactory.create()` phase — before `SwaggerModule.createDocument()` is called. It uses `require()` to load each companion docs file, which executes `docs()` and writes `Reflect` metadata directly onto the controller methods, exactly as TypeScript decorator syntax would at class-definition time.
356
476
 
357
- By the time `SwaggerModule.createDocument()` scans for metadata, all of it is already in place.
477
+ By the time `SwaggerModule.createDocument()` scans for metadata, all of it is already in place. No monkey-patching, no runtime proxies.
358
478
 
359
- The `generate` CLI uses **static analysis only** (`ts-morph`) — it reads TypeScript AST without executing any project code. All user-supplied paths and values are validated and sanitised before use.
479
+ The `generate` CLI uses `ts-morph` for static analysis — it reads the TypeScript AST without executing any project code. All user-supplied paths and glob patterns are validated and sanitised before use.
360
480
 
361
481
  ## License
362
482
 
363
- MIT
483
+ [MIT](https://github.com/MarvinRF/nest-docfy/blob/main/LICENSE) © Marvin Rocha
@@ -0,0 +1,18 @@
1
+ import type { ControllerInfo } from './extract-methods';
2
+ export interface CheckIssue {
3
+ controllerClass: string;
4
+ controllerFile: string;
5
+ docsFile: string;
6
+ kind: 'missing-file' | 'undocumented-methods';
7
+ /** Populated when kind === 'undocumented-methods' */
8
+ methods?: string[];
9
+ }
10
+ export declare function getDocumentedMethods(docsFilePath: string): Set<string>;
11
+ /**
12
+ * Checks all controllers for documentation drift:
13
+ * - Missing companion docs file
14
+ * - HTTP methods in the controller that are not present in the docs file
15
+ *
16
+ * Returns an array of issues. Empty array means everything is in sync.
17
+ */
18
+ export declare function checkControllers(controllers: ControllerInfo[], format: 'ts' | 'js'): CheckIssue[];