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 +287 -167
- package/dist/cli/check.d.ts +18 -0
- package/dist/cli/check.js +108 -0
- package/dist/cli/check.js.map +1 -0
- package/dist/cli/extract-methods.d.ts +13 -0
- package/dist/cli/extract-methods.js +165 -1
- package/dist/cli/extract-methods.js.map +1 -1
- package/dist/cli/generate-file.js +35 -2
- package/dist/cli/generate-file.js.map +1 -1
- package/dist/cli/index.js +68 -0
- package/dist/cli/index.js.map +1 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -1,49 +1,71 @@
|
|
|
1
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/nestjs-docfy)
|
|
10
|
+
[](https://www.npmjs.com/package/nestjs-docfy)
|
|
11
|
+
[](https://github.com/MarvinRF/nest-docfy/commits/main)
|
|
12
|
+
[](https://github.com/MarvinRF/nest-docfy/issues)
|
|
13
|
+
[](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
|
-
##
|
|
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
|
|
47
|
+
**Before** — Swagger decorators scattered across your controller:
|
|
8
48
|
|
|
9
49
|
```ts
|
|
10
50
|
// users.controller.ts
|
|
11
|
-
@ApiTags(
|
|
12
|
-
@Controller(
|
|
51
|
+
@ApiTags("users")
|
|
52
|
+
@Controller("users")
|
|
13
53
|
export class UsersController {
|
|
14
54
|
@Get()
|
|
15
|
-
@ApiOperation({ summary:
|
|
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:
|
|
62
|
+
@ApiOperation({ summary: "Create a user" })
|
|
32
63
|
@ApiBody({ type: CreateUserDto })
|
|
33
|
-
@ApiResponse({ status: 201, type: UserEntity })
|
|
34
|
-
@ApiResponse({ status: 400, description:
|
|
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(
|
|
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(
|
|
92
|
+
classDecorators: [ApiTags("users")],
|
|
79
93
|
methods: {
|
|
80
94
|
findAll: [
|
|
81
|
-
ApiOperation({ summary:
|
|
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:
|
|
99
|
+
ApiOperation({ summary: "Create a user" }),
|
|
86
100
|
ApiBody({ type: CreateUserDto }),
|
|
87
|
-
ApiResponse({ status: 201, type: UserEntity }),
|
|
88
|
-
ApiResponse({ status: 400, description:
|
|
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
|
|
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
|
-
##
|
|
122
|
+
## Quick start
|
|
113
123
|
|
|
114
|
-
### 1. Import
|
|
124
|
+
### 1. Import DocfyModule
|
|
115
125
|
|
|
116
126
|
```ts
|
|
117
127
|
// app.module.ts
|
|
118
|
-
import { Module } from
|
|
119
|
-
import { DocfyModule } from
|
|
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
|
-
|
|
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
|
|
136
|
-
import { WithDocs } from
|
|
147
|
+
import { Controller, Get, Post, Body } from "@nestjs/common";
|
|
148
|
+
import { WithDocs } from "nestjs-docfy";
|
|
137
149
|
|
|
138
150
|
@WithDocs()
|
|
139
|
-
@Controller(
|
|
151
|
+
@Controller("users")
|
|
140
152
|
export class UsersController {
|
|
141
|
-
//
|
|
153
|
+
// route handlers only — no Swagger decorators here
|
|
142
154
|
}
|
|
143
155
|
```
|
|
144
156
|
|
|
145
|
-
### 3. Generate
|
|
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
|
-
|
|
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
|
-
//
|
|
157
|
-
import { docs } from
|
|
158
|
-
import { ApiTags, ApiOperation, ApiResponse } from
|
|
159
|
-
import { UsersController } from
|
|
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 /
|
|
188
|
+
// GET / → async findAll(): Promise<UserEntity[]>
|
|
167
189
|
findAll: [
|
|
168
|
-
|
|
169
|
-
|
|
190
|
+
ApiOperation({ summary: "Find all" }),
|
|
191
|
+
ApiResponse({ status: 200, description: "OK", type: [UserEntity] }),
|
|
170
192
|
],
|
|
171
193
|
|
|
172
|
-
//
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
-
|
|
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
|
-
|
|
207
|
+
No changes to `main.ts` are needed. `DocfyModule` applies all metadata before `SwaggerModule.createDocument()` is called.
|
|
207
208
|
|
|
208
|
-
|
|
209
|
+
## CLI — generate
|
|
209
210
|
|
|
210
211
|
```bash
|
|
211
|
-
|
|
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
|
|
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
|
-
|
|
|
242
|
-
| Nest CLI
|
|
243
|
-
| Generic
|
|
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
|
-
###
|
|
239
|
+
### Idempotency and --force
|
|
246
240
|
|
|
247
|
-
|
|
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
|
-
|
|
251
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
264
|
+
npx nestjs-docfy check [options]
|
|
259
265
|
```
|
|
260
266
|
|
|
261
|
-
|
|
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
|
-
|
|
275
|
+
**What it checks:**
|
|
264
276
|
|
|
265
|
-
|
|
277
|
+
- Controllers with HTTP methods but no companion docs file
|
|
278
|
+
- Controllers that have methods added since the last `generate` run
|
|
266
279
|
|
|
267
|
-
|
|
280
|
+
**Example output:**
|
|
268
281
|
|
|
269
|
-
|
|
282
|
+
```text
|
|
283
|
+
✖ UsersController — undocumented methods: updateProfile, deleteAccount
|
|
284
|
+
→ run nestjs-docfy generate --force to merge new methods
|
|
270
285
|
|
|
271
|
-
|
|
286
|
+
✖ 2 controller(s) out of sync.
|
|
287
|
+
```
|
|
272
288
|
|
|
273
|
-
|
|
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
|
-
```
|
|
278
|
-
|
|
279
|
-
|
|
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
|
-
|
|
282
|
-
|
|
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
|
|
327
|
+
Also sets `DOCFY_MARKER` metadata on the class, available for external introspection:
|
|
298
328
|
|
|
299
329
|
```ts
|
|
300
|
-
import { DOCFY_MARKER } from
|
|
330
|
+
import { DOCFY_MARKER } from "nestjs-docfy";
|
|
301
331
|
|
|
302
|
-
|
|
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
|
-
|
|
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: [...],
|
|
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[]` —
|
|
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
|
-
|
|
388
|
+
## class-validator inference
|
|
327
389
|
|
|
328
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
465
|
+
Reset the controller registry between test suites to avoid cross-contamination:
|
|
344
466
|
|
|
345
467
|
```ts
|
|
346
|
-
import { resetDocfyRegistry } from
|
|
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
|
-
|
|
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
|
|
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[];
|