nestjs-docfy 0.2.8 → 0.3.1

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.
Files changed (58) hide show
  1. package/README.md +261 -0
  2. package/dist/attach-tag-groups.d.ts +14 -0
  3. package/dist/attach-tag-groups.js +24 -0
  4. package/dist/attach-tag-groups.js.map +1 -0
  5. package/dist/cli/build-openapi-patch.d.ts +45 -0
  6. package/dist/cli/build-openapi-patch.js +151 -0
  7. package/dist/cli/build-openapi-patch.js.map +1 -0
  8. package/dist/cli/coverage.d.ts +15 -0
  9. package/dist/cli/coverage.js +34 -0
  10. package/dist/cli/coverage.js.map +1 -0
  11. package/dist/cli/eval-decorator-args.d.ts +39 -0
  12. package/dist/cli/eval-decorator-args.js +115 -0
  13. package/dist/cli/eval-decorator-args.js.map +1 -0
  14. package/dist/cli/extract-docs-config.d.ts +19 -0
  15. package/dist/cli/extract-docs-config.js +89 -0
  16. package/dist/cli/extract-docs-config.js.map +1 -0
  17. package/dist/cli/index.js +287 -0
  18. package/dist/cli/index.js.map +1 -1
  19. package/dist/cli/lint.d.ts +33 -0
  20. package/dist/cli/lint.js +211 -0
  21. package/dist/cli/lint.js.map +1 -0
  22. package/dist/cli/merge-spec-patch.d.ts +57 -0
  23. package/dist/cli/merge-spec-patch.js +115 -0
  24. package/dist/cli/merge-spec-patch.js.map +1 -0
  25. package/dist/cli/patch-spec.d.ts +31 -0
  26. package/dist/cli/patch-spec.js +82 -0
  27. package/dist/cli/patch-spec.js.map +1 -0
  28. package/dist/docfy-ui.module.d.ts +48 -0
  29. package/dist/docfy-ui.module.js +72 -0
  30. package/dist/docfy-ui.module.js.map +1 -0
  31. package/dist/docfy.module.js +9 -5
  32. package/dist/docfy.module.js.map +1 -1
  33. package/dist/docs.d.ts +13 -0
  34. package/dist/docs.js +4 -0
  35. package/dist/docs.js.map +1 -1
  36. package/dist/index.d.ts +3 -0
  37. package/dist/index.js +5 -1
  38. package/dist/index.js.map +1 -1
  39. package/dist/registry.d.ts +2 -1
  40. package/dist/registry.js +11 -1
  41. package/dist/registry.js.map +1 -1
  42. package/dist/require-ts.d.ts +32 -0
  43. package/dist/require-ts.js +122 -0
  44. package/dist/require-ts.js.map +1 -0
  45. package/dist/resolve-docs-path.d.ts +10 -1
  46. package/dist/resolve-docs-path.js +31 -3
  47. package/dist/resolve-docs-path.js.map +1 -1
  48. package/dist/resolve-source-from-stack.d.ts +35 -0
  49. package/dist/resolve-source-from-stack.js +153 -0
  50. package/dist/resolve-source-from-stack.js.map +1 -0
  51. package/dist/tag-group-registry.d.ts +9 -0
  52. package/dist/tag-group-registry.js +32 -0
  53. package/dist/tag-group-registry.js.map +1 -0
  54. package/dist/testing.js +2 -0
  55. package/dist/testing.js.map +1 -1
  56. package/dist/with-docs.decorator.js +7 -1
  57. package/dist/with-docs.decorator.js.map +1 -1
  58. package/package.json +5 -1
@@ -0,0 +1,211 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.parseDocsFileMethods = parseDocsFileMethods;
4
+ exports.lintControllers = lintControllers;
5
+ const ts_morph_1 = require("ts-morph");
6
+ const scan_controllers_1 = require("./scan-controllers");
7
+ const IDENTIFIER_RE = /^[$_a-zA-Z][$_a-zA-Z0-9]*$/;
8
+ function getObjectLiteralArgAt(call, index) {
9
+ try {
10
+ const args = call.getArguments();
11
+ if (args.length <= index)
12
+ return null;
13
+ const arg = args[index];
14
+ if (arg.getKind() === ts_morph_1.SyntaxKind.ObjectLiteralExpression)
15
+ return arg;
16
+ return null;
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ }
22
+ function getNumericProperty(obj, name) {
23
+ try {
24
+ const prop = obj.getProperty(name);
25
+ if (!prop || prop.getKind() !== ts_morph_1.SyntaxKind.PropertyAssignment)
26
+ return null;
27
+ const init = prop.getInitializer();
28
+ if (!init)
29
+ return null;
30
+ const val = Number(init.getText());
31
+ return Number.isFinite(val) ? val : null;
32
+ }
33
+ catch {
34
+ return null;
35
+ }
36
+ }
37
+ /**
38
+ * Parses a docs file's `docs(Controller, { methods: { ... } })` call via AST
39
+ * (not regex) to inspect actual decorator arguments — needed to check for
40
+ * `summary`, `status`, and `description` properties rather than just names.
41
+ */
42
+ function parseDocsFileMethods(docsFilePath) {
43
+ const result = new Map();
44
+ let project;
45
+ try {
46
+ project = new ts_morph_1.Project({
47
+ skipAddingFilesFromTsConfig: true,
48
+ skipFileDependencyResolution: true,
49
+ skipLoadingLibFiles: true,
50
+ });
51
+ }
52
+ catch {
53
+ return result;
54
+ }
55
+ let sourceFile;
56
+ try {
57
+ sourceFile = project.addSourceFileAtPath(docsFilePath);
58
+ }
59
+ catch {
60
+ return result;
61
+ }
62
+ try {
63
+ const docsCalls = sourceFile
64
+ .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
65
+ .filter((c) => {
66
+ try {
67
+ return c.getExpression().getText() === 'docs';
68
+ }
69
+ catch {
70
+ return false;
71
+ }
72
+ });
73
+ for (const docsCall of docsCalls) {
74
+ const configArg = getObjectLiteralArgAt(docsCall, 1);
75
+ if (!configArg)
76
+ continue;
77
+ const methodsProp = configArg.getProperty('methods');
78
+ if (!methodsProp || methodsProp.getKind() !== ts_morph_1.SyntaxKind.PropertyAssignment)
79
+ continue;
80
+ const methodsInit = methodsProp.getInitializer();
81
+ if (!methodsInit || methodsInit.getKind() !== ts_morph_1.SyntaxKind.ObjectLiteralExpression)
82
+ continue;
83
+ for (const prop of methodsInit.getProperties()) {
84
+ if (prop.getKind() !== ts_morph_1.SyntaxKind.PropertyAssignment)
85
+ continue;
86
+ const pa = prop;
87
+ let name;
88
+ try {
89
+ name = pa.getName();
90
+ }
91
+ catch {
92
+ continue;
93
+ }
94
+ if (!IDENTIFIER_RE.test(name))
95
+ continue;
96
+ const init = pa.getInitializer();
97
+ if (!init || init.getKind() !== ts_morph_1.SyntaxKind.ArrayLiteralExpression)
98
+ continue;
99
+ const info = {
100
+ hasSummary: false,
101
+ responseStatuses: new Set(),
102
+ hasApiBody: false,
103
+ hasBodyDescription: false,
104
+ };
105
+ for (const el of init.getElements()) {
106
+ if (el.getKind() !== ts_morph_1.SyntaxKind.CallExpression)
107
+ continue;
108
+ const callEl = el;
109
+ let calleeName;
110
+ try {
111
+ calleeName = callEl.getExpression().getText();
112
+ }
113
+ catch {
114
+ continue;
115
+ }
116
+ const objArg = getObjectLiteralArgAt(callEl, 0);
117
+ if (calleeName === 'ApiOperation') {
118
+ if (objArg?.getProperty('summary'))
119
+ info.hasSummary = true;
120
+ }
121
+ else if (calleeName === 'ApiResponse') {
122
+ if (objArg) {
123
+ const status = getNumericProperty(objArg, 'status');
124
+ if (status !== null)
125
+ info.responseStatuses.add(status);
126
+ }
127
+ }
128
+ else if (calleeName === 'ApiBody') {
129
+ info.hasApiBody = true;
130
+ if (objArg?.getProperty('description'))
131
+ info.hasBodyDescription = true;
132
+ }
133
+ }
134
+ result.set(name, info);
135
+ }
136
+ }
137
+ }
138
+ catch {
139
+ // best-effort — return whatever was collected before the failure
140
+ }
141
+ return result;
142
+ }
143
+ function buildRoute(httpDecorator, controllerPath, httpPath) {
144
+ const base = controllerPath ? controllerPath.replace(/^\/+|\/+$/g, '') : '';
145
+ const sub = httpPath ? httpPath.replace(/^\/+|\/+$/g, '') : '';
146
+ const combined = [base, sub].filter(Boolean).join('/');
147
+ return `${httpDecorator.toUpperCase()} /${combined}`;
148
+ }
149
+ /**
150
+ * Checks documentation quality for already-documented HTTP methods:
151
+ * - Missing `summary` in `ApiOperation`
152
+ * - Missing `400` response for endpoints that accept a request body
153
+ * - Missing `description` on `ApiBody` for endpoints that accept a request body
154
+ *
155
+ * Controllers with no companion docs file, and methods not yet present in
156
+ * the docs file, are skipped — those are reported by the `check` command.
157
+ */
158
+ function lintControllers(controllers, format) {
159
+ const issues = [];
160
+ for (const ctrl of controllers) {
161
+ if (!ctrl.hasDocsFile)
162
+ continue;
163
+ const docsFile = (0, scan_controllers_1.deriveDocsFilePath)(ctrl.filePath, format);
164
+ const docsInfo = parseDocsFileMethods(docsFile);
165
+ for (const m of ctrl.methods) {
166
+ if (m.httpDecorator === null)
167
+ continue;
168
+ if (!IDENTIFIER_RE.test(m.name))
169
+ continue;
170
+ const info = docsInfo.get(m.name);
171
+ if (!info)
172
+ continue;
173
+ const route = buildRoute(m.httpDecorator, ctrl.controllerPath, m.httpPath);
174
+ const hasBody = m.params.some((p) => p.nestDecorator === '@Body');
175
+ if (!info.hasSummary) {
176
+ issues.push({
177
+ controllerClass: ctrl.className,
178
+ controllerFile: ctrl.filePath,
179
+ method: m.name,
180
+ route,
181
+ rule: 'missing-summary',
182
+ message: 'Missing operation summary',
183
+ });
184
+ }
185
+ if (hasBody) {
186
+ if (!info.responseStatuses.has(400)) {
187
+ issues.push({
188
+ controllerClass: ctrl.className,
189
+ controllerFile: ctrl.filePath,
190
+ method: m.name,
191
+ route,
192
+ rule: 'missing-400-response',
193
+ message: 'Missing 400 response',
194
+ });
195
+ }
196
+ if (!info.hasApiBody || !info.hasBodyDescription) {
197
+ issues.push({
198
+ controllerClass: ctrl.className,
199
+ controllerFile: ctrl.filePath,
200
+ method: m.name,
201
+ route,
202
+ rule: 'missing-body-description',
203
+ message: 'Missing request body description',
204
+ });
205
+ }
206
+ }
207
+ }
208
+ }
209
+ return issues;
210
+ }
211
+ //# sourceMappingURL=lint.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/cli/lint.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,57 @@
1
+ import type { OpenApiSchema, OperationPatch, SpecPatch } from './build-openapi-patch';
2
+ export interface OpenApiDocument {
3
+ paths?: Record<string, Record<string, OpenApiOperation>>;
4
+ [key: string]: unknown;
5
+ }
6
+ export interface OpenApiOperation {
7
+ tags?: string[];
8
+ summary?: string;
9
+ description?: string;
10
+ deprecated?: boolean;
11
+ security?: Array<Record<string, string[]>>;
12
+ parameters?: Array<{
13
+ name: string;
14
+ in: string;
15
+ required?: boolean;
16
+ schema: OpenApiSchema;
17
+ }>;
18
+ requestBody?: {
19
+ required?: boolean;
20
+ content: Record<string, {
21
+ schema: OpenApiSchema;
22
+ }>;
23
+ };
24
+ responses?: Record<string, {
25
+ description?: string;
26
+ content?: Record<string, {
27
+ schema: OpenApiSchema;
28
+ }>;
29
+ }>;
30
+ [key: string]: unknown;
31
+ }
32
+ /**
33
+ * Merges one operation-level patch into an existing OpenAPI operation
34
+ * object. Scalars (summary/description/deprecated/requestBody) overwrite;
35
+ * collections (tags/security/parameters/responses) merge additively so a
36
+ * docs patch only ever adds information, never silently drops whatever the
37
+ * base document (from @nestjs/swagger's own decorator/type inference) had.
38
+ */
39
+ export declare function mergeOperation(existing: OpenApiOperation, patch: OperationPatch): OpenApiOperation;
40
+ export interface MergeSpecPatchResult {
41
+ document: OpenApiDocument;
42
+ /** "METHOD /path" entries from the patch that had no matching operation in the base document. */
43
+ unmatchedRoutes: string[];
44
+ }
45
+ /**
46
+ * Merges a statically-computed SpecPatch (see build-openapi-patch.ts) into
47
+ * an already-built OpenAPI document — the output of `SwaggerModule.createDocument()`,
48
+ * fetched from a running app's `/api-json` or read from a generated file.
49
+ *
50
+ * Matches by path + HTTP method, never by class identity, which is the
51
+ * whole point: it works regardless of whether the live app's controller
52
+ * class is reachable from this process (see README's "Not supported:
53
+ * webpack: true" section for why that reachability can't be assumed).
54
+ *
55
+ * Does not mutate the input document.
56
+ */
57
+ export declare function mergeSpecPatch(document: OpenApiDocument, patch: SpecPatch): MergeSpecPatchResult;
@@ -0,0 +1,115 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.mergeOperation = mergeOperation;
4
+ exports.mergeSpecPatch = mergeSpecPatch;
5
+ /**
6
+ * Unions tags case-insensitively, keeping whichever casing was already in
7
+ * the base document's `tags` so the merge never produces what looks like
8
+ * two different groups in a UI that groups operations by tag (e.g.
9
+ * @nestjs/swagger's auto-generated "Auth" colliding with an `ApiTags('auth')`
10
+ * in a docs file — same logical tag, different casing).
11
+ */
12
+ function mergeTags(existing, incoming) {
13
+ if (!incoming)
14
+ return existing;
15
+ const result = [...(existing ?? [])];
16
+ const seenLower = new Set(result.map((t) => t.toLowerCase()));
17
+ for (const tag of incoming) {
18
+ if (!seenLower.has(tag.toLowerCase())) {
19
+ result.push(tag);
20
+ seenLower.add(tag.toLowerCase());
21
+ }
22
+ }
23
+ return result;
24
+ }
25
+ function mergeSecurity(existing, incoming) {
26
+ if (!incoming)
27
+ return existing;
28
+ const keys = new Set((existing ?? []).map((e) => Object.keys(e).join(',')));
29
+ const merged = [...(existing ?? [])];
30
+ for (const entry of incoming) {
31
+ const key = Object.keys(entry).join(',');
32
+ if (!keys.has(key)) {
33
+ merged.push(entry);
34
+ keys.add(key);
35
+ }
36
+ }
37
+ return merged;
38
+ }
39
+ function mergeParameters(existing, incoming) {
40
+ if (!incoming)
41
+ return existing;
42
+ const key = (p) => `${p.in}:${p.name}`;
43
+ const seen = new Set((existing ?? []).map(key));
44
+ const merged = [...(existing ?? [])];
45
+ for (const param of incoming) {
46
+ if (!seen.has(key(param))) {
47
+ merged.push(param);
48
+ seen.add(key(param));
49
+ }
50
+ }
51
+ return merged;
52
+ }
53
+ function mergeResponses(existing, incoming) {
54
+ if (!incoming)
55
+ return existing;
56
+ const merged = { ...(existing ?? {}) };
57
+ for (const [status, value] of Object.entries(incoming)) {
58
+ merged[status] = { ...merged[status], ...value };
59
+ }
60
+ return merged;
61
+ }
62
+ /**
63
+ * Merges one operation-level patch into an existing OpenAPI operation
64
+ * object. Scalars (summary/description/deprecated/requestBody) overwrite;
65
+ * collections (tags/security/parameters/responses) merge additively so a
66
+ * docs patch only ever adds information, never silently drops whatever the
67
+ * base document (from @nestjs/swagger's own decorator/type inference) had.
68
+ */
69
+ function mergeOperation(existing, patch) {
70
+ return {
71
+ ...existing,
72
+ ...(patch.summary !== undefined ? { summary: patch.summary } : {}),
73
+ ...(patch.description !== undefined ? { description: patch.description } : {}),
74
+ ...(patch.deprecated !== undefined ? { deprecated: patch.deprecated } : {}),
75
+ ...(patch.requestBody !== undefined ? { requestBody: patch.requestBody } : {}),
76
+ tags: mergeTags(existing.tags, patch.tags),
77
+ security: mergeSecurity(existing.security, patch.security),
78
+ parameters: mergeParameters(existing.parameters, patch.parameters),
79
+ responses: mergeResponses(existing.responses, patch.responses),
80
+ };
81
+ }
82
+ /**
83
+ * Merges a statically-computed SpecPatch (see build-openapi-patch.ts) into
84
+ * an already-built OpenAPI document — the output of `SwaggerModule.createDocument()`,
85
+ * fetched from a running app's `/api-json` or read from a generated file.
86
+ *
87
+ * Matches by path + HTTP method, never by class identity, which is the
88
+ * whole point: it works regardless of whether the live app's controller
89
+ * class is reachable from this process (see README's "Not supported:
90
+ * webpack: true" section for why that reachability can't be assumed).
91
+ *
92
+ * Does not mutate the input document.
93
+ */
94
+ function mergeSpecPatch(document, patch) {
95
+ const paths = {};
96
+ for (const [route, methods] of Object.entries(document.paths ?? {})) {
97
+ paths[route] = { ...methods };
98
+ }
99
+ const unmatchedRoutes = [];
100
+ for (const [route, methods] of Object.entries(patch)) {
101
+ for (const [httpMethod, opPatch] of Object.entries(methods)) {
102
+ const existingOperation = paths[route]?.[httpMethod];
103
+ if (!existingOperation) {
104
+ unmatchedRoutes.push(`${httpMethod.toUpperCase()} ${route}`);
105
+ continue;
106
+ }
107
+ paths[route] = {
108
+ ...paths[route],
109
+ [httpMethod]: mergeOperation(existingOperation, opPatch),
110
+ };
111
+ }
112
+ }
113
+ return { document: { ...document, paths }, unmatchedRoutes };
114
+ }
115
+ //# sourceMappingURL=merge-spec-patch.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merge-spec-patch.js","sourceRoot":"","sources":["../../src/cli/merge-spec-patch.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,31 @@
1
+ import { OpenApiDocument } from './merge-spec-patch';
2
+ import type { ControllerInfo } from './extract-methods';
3
+ export interface PatchSpecResult {
4
+ document: OpenApiDocument;
5
+ /** How many "METHOD /path" operations were touched by at least one docs file. */
6
+ patchedOperationCount: number;
7
+ /** Patch entries that named a route+method absent from the base document. */
8
+ unmatchedRoutes: string[];
9
+ /** Controllers scanned that have no companion docs file at all — informational, not an error. */
10
+ controllersWithoutDocs: string[];
11
+ /** Docs files that exist but couldn't be parsed (no docs(...) call found, or a syntax error). */
12
+ unparseableDocsFiles: string[];
13
+ }
14
+ /**
15
+ * Computes the fully-patched OpenAPI document from an already-built base
16
+ * document plus every controller's companion docs file — all via static
17
+ * analysis (ts-morph), no runtime require() of any docs file, no decorator
18
+ * application, no dependency on a live class reference matching the one
19
+ * the running app actually uses.
20
+ *
21
+ * This is the alternative to DocfyModule's runtime pipeline for apps where
22
+ * that pipeline structurally cannot work (NestJS CLI's `webpack: true`
23
+ * build mode — see the README's "Not supported" section). Run this as a
24
+ * build step instead: generate the OpenAPI document however you already
25
+ * do (SwaggerModule.createDocument + write to a file, or fetch a running
26
+ * app's /api-json), then patch it with this.
27
+ *
28
+ * `readDocsFile` is injected so this function stays pure/testable —
29
+ * the real CLI command supplies `fs.readFileSync`.
30
+ */
31
+ export declare function computePatchedDocument(document: OpenApiDocument, controllers: ControllerInfo[], format: 'ts' | 'js', readDocsFile: (absolutePath: string) => string | null): PatchSpecResult;
@@ -0,0 +1,82 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.computePatchedDocument = computePatchedDocument;
4
+ const scan_controllers_1 = require("./scan-controllers");
5
+ const extract_docs_config_1 = require("./extract-docs-config");
6
+ const build_openapi_patch_1 = require("./build-openapi-patch");
7
+ const merge_spec_patch_1 = require("./merge-spec-patch");
8
+ /**
9
+ * Merges two SpecPatch maps, deep-merging at the operation level (not a
10
+ * shallow per-method overwrite) — two different controllers can
11
+ * legitimately produce a patch for the exact same path + method (e.g. a
12
+ * gateway and the microservice it proxies to, both documenting the same
13
+ * logical route under their own controller). A shallow overwrite would let
14
+ * whichever controller is scanned second silently wipe out fields the
15
+ * first one set, rather than only adding to them. Reuses mergeOperation —
16
+ * the same additive-collections/overwrite-scalars semantics already used
17
+ * when merging a patch into the base document.
18
+ */
19
+ function mergePatches(a, b) {
20
+ const result = { ...a };
21
+ for (const [route, methods] of Object.entries(b)) {
22
+ const merged = { ...result[route] };
23
+ for (const [httpMethod, opPatch] of Object.entries(methods)) {
24
+ const existing = merged[httpMethod];
25
+ merged[httpMethod] = existing
26
+ ? (0, merge_spec_patch_1.mergeOperation)(existing, opPatch)
27
+ : opPatch;
28
+ }
29
+ result[route] = merged;
30
+ }
31
+ return result;
32
+ }
33
+ /**
34
+ * Computes the fully-patched OpenAPI document from an already-built base
35
+ * document plus every controller's companion docs file — all via static
36
+ * analysis (ts-morph), no runtime require() of any docs file, no decorator
37
+ * application, no dependency on a live class reference matching the one
38
+ * the running app actually uses.
39
+ *
40
+ * This is the alternative to DocfyModule's runtime pipeline for apps where
41
+ * that pipeline structurally cannot work (NestJS CLI's `webpack: true`
42
+ * build mode — see the README's "Not supported" section). Run this as a
43
+ * build step instead: generate the OpenAPI document however you already
44
+ * do (SwaggerModule.createDocument + write to a file, or fetch a running
45
+ * app's /api-json), then patch it with this.
46
+ *
47
+ * `readDocsFile` is injected so this function stays pure/testable —
48
+ * the real CLI command supplies `fs.readFileSync`.
49
+ */
50
+ function computePatchedDocument(document, controllers, format, readDocsFile) {
51
+ let patch = {};
52
+ const controllersWithoutDocs = [];
53
+ const unparseableDocsFiles = [];
54
+ for (const ctrl of controllers) {
55
+ if (!ctrl.hasDocsFile) {
56
+ controllersWithoutDocs.push(ctrl.className);
57
+ continue;
58
+ }
59
+ const docsPath = (0, scan_controllers_1.deriveDocsFilePath)(ctrl.filePath, format);
60
+ const content = readDocsFile(docsPath);
61
+ if (content === null) {
62
+ unparseableDocsFiles.push(docsPath);
63
+ continue;
64
+ }
65
+ const config = (0, extract_docs_config_1.extractDocsConfig)(content);
66
+ if (!config) {
67
+ unparseableDocsFiles.push(docsPath);
68
+ continue;
69
+ }
70
+ patch = mergePatches(patch, (0, build_openapi_patch_1.buildOpenApiPatch)(ctrl, config));
71
+ }
72
+ const { document: patchedDocument, unmatchedRoutes } = (0, merge_spec_patch_1.mergeSpecPatch)(document, patch);
73
+ const patchedOperationCount = Object.values(patch).reduce((count, methods) => count + Object.keys(methods).length, 0);
74
+ return {
75
+ document: patchedDocument,
76
+ patchedOperationCount,
77
+ unmatchedRoutes,
78
+ controllersWithoutDocs,
79
+ unparseableDocsFiles,
80
+ };
81
+ }
82
+ //# sourceMappingURL=patch-spec.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"patch-spec.js","sourceRoot":"","sources":["../../src/cli/patch-spec.ts"],"names":[],"mappings":";;AA6DA,wDA6CC;AA1GD,yDAAwD;AACxD,+DAA0D;AAC1D,+DAAqF;AACrF,yDAAuG;AAevG;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CAAC,CAAY,EAAE,CAAY;IAC9C,MAAM,MAAM,GAAc,EAAE,GAAG,CAAC,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,MAAM,GAAmC,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACpE,KAAK,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;YACpC,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ;gBAC3B,CAAC,CAAE,IAAA,iCAAc,EAAC,QAA4B,EAAE,OAAO,CAAoB;gBAC3E,CAAC,CAAC,OAAO,CAAC;QACd,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,sBAAsB,CACpC,QAAyB,EACzB,WAA6B,EAC7B,MAAmB,EACnB,YAAqD;IAErD,IAAI,KAAK,GAAc,EAAE,CAAC;IAC1B,MAAM,sBAAsB,GAAa,EAAE,CAAC;IAC5C,MAAM,oBAAoB,GAAa,EAAE,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC5C,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,IAAA,qCAAkB,EAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,uCAAiB,EAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,SAAS;QACX,CAAC;QAED,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,IAAA,uCAAiB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,GAAG,IAAA,iCAAc,EAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvF,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CACvD,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EACvD,CAAC,CACF,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,eAAe;QACzB,qBAAqB;QACrB,eAAe;QACf,sBAAsB;QACtB,oBAAoB;KACrB,CAAC;AACJ,CAAC"}
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Minimal structural shape of what `DocfyUiModule.setup()` needs from a
3
+ * NestJS application instance — just enough to register Express-style
4
+ * middleware. Deliberately not typed as `INestApplication` so this file
5
+ * doesn't pull `@nestjs/common`'s full surface into a narrow concern, and
6
+ * not typed as `express.Application` so consumers don't need `@types/express`
7
+ * just to call this function.
8
+ */
9
+ export interface DocfyUiSetupTarget {
10
+ use(...args: unknown[]): unknown;
11
+ }
12
+ export interface DocfyUiSetupOptions {
13
+ /**
14
+ * Path to a pre-built OpenAPI JSON file to serve at `/api-json` instead
15
+ * of whatever the app's own SwaggerModule produces live.
16
+ *
17
+ * Required when the app is built with NestJS CLI's `webpack: true` —
18
+ * DocfyModule's runtime metadata pipeline cannot apply docs files there
19
+ * (see the README's "Not supported: webpack: true" section for why).
20
+ * Generate this file ahead of time with:
21
+ *
22
+ * npx nestjs-docfy patch-spec --spec <url-or-path> --out <path>
23
+ *
24
+ * Call `DocfyUiModule.setup()` with this option *before*
25
+ * `SwaggerModule.setup()` in your bootstrap — Express resolves routes
26
+ * in registration order, so the static, patched document takes
27
+ * precedence over the live (and, under webpack, incomplete) one for
28
+ * any request to `/api-json`.
29
+ */
30
+ staticSpecPath?: string;
31
+ }
32
+ /**
33
+ * Serves the published `docfy-ui` package's static build at `mountPath`,
34
+ * giving a `nestjs-docfy`-equipped app a documentation UI by default —
35
+ * the same role `SwaggerModule.setup()` + `swagger-ui-express` play for
36
+ * raw Swagger UI, but for `docfy-ui`.
37
+ *
38
+ * Caveat: `docfy-ui` currently renders with React Router's `BrowserRouter`
39
+ * and no configurable `basename`, so deep client-side routes (e.g.
40
+ * reloading `/users/findAllUsers` directly) only resolve correctly when
41
+ * `mountPath` is `/` — the application's root. Mounting elsewhere (e.g.
42
+ * `/docs`) still serves the UI and its initial load works, but in-app
43
+ * navigation/reload at a non-root path is not yet supported by `docfy-ui`
44
+ * itself.
45
+ */
46
+ export declare class DocfyUiModule {
47
+ static setup(mountPath: string, app: DocfyUiSetupTarget, options?: DocfyUiSetupOptions): void;
48
+ }
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.DocfyUiModule = void 0;
37
+ const fs = __importStar(require("fs"));
38
+ const path = __importStar(require("path"));
39
+ const express = __importStar(require("express"));
40
+ /**
41
+ * Serves the published `docfy-ui` package's static build at `mountPath`,
42
+ * giving a `nestjs-docfy`-equipped app a documentation UI by default —
43
+ * the same role `SwaggerModule.setup()` + `swagger-ui-express` play for
44
+ * raw Swagger UI, but for `docfy-ui`.
45
+ *
46
+ * Caveat: `docfy-ui` currently renders with React Router's `BrowserRouter`
47
+ * and no configurable `basename`, so deep client-side routes (e.g.
48
+ * reloading `/users/findAllUsers` directly) only resolve correctly when
49
+ * `mountPath` is `/` — the application's root. Mounting elsewhere (e.g.
50
+ * `/docs`) still serves the UI and its initial load works, but in-app
51
+ * navigation/reload at a non-root path is not yet supported by `docfy-ui`
52
+ * itself.
53
+ */
54
+ class DocfyUiModule {
55
+ static setup(mountPath, app, options = {}) {
56
+ if (options.staticSpecPath) {
57
+ const specJson = fs.readFileSync(options.staticSpecPath, 'utf8');
58
+ app.use('/api-json', (_req, res) => {
59
+ res.setHeader('Content-Type', 'application/json');
60
+ res.end(specJson);
61
+ });
62
+ }
63
+ const indexHtmlPath = require.resolve('docfy-ui/dist/index.html');
64
+ const uiDir = path.dirname(indexHtmlPath);
65
+ app.use(mountPath, express.static(uiDir));
66
+ app.use(mountPath, (_req, res) => {
67
+ res.sendFile(path.join(uiDir, 'index.html'));
68
+ });
69
+ }
70
+ }
71
+ exports.DocfyUiModule = DocfyUiModule;
72
+ //# sourceMappingURL=docfy-ui.module.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"docfy-ui.module.js","sourceRoot":"","sources":["../src/docfy-ui.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAC7B,iDAAmC;AAmCnC;;;;;;;;;;;;;GAaG;AACH,MAAa,aAAa;IACxB,MAAM,CAAC,KAAK,CACV,SAAiB,EACjB,GAAuB,EACvB,UAA+B,EAAE;QAEjC,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;YACjE,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAqB,EAAE,GAAqB,EAAE,EAAE;gBACpE,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;gBAClD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAE1C,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAqB,EAAE,GAAqB,EAAE,EAAE;YAClE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAtBD,sCAsBC"}