nestjs-docfy 0.3.6 → 0.4.0
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 +3 -1
- package/dist/docfy-ui.module.d.ts +26 -10
- package/dist/docfy-ui.module.js +42 -6
- package/dist/docfy-ui.module.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +10 -1
package/README.md
CHANGED
|
@@ -519,7 +519,7 @@ Adds the `x-tagGroups` extension to a Swagger document, built from groups regist
|
|
|
519
519
|
|
|
520
520
|
### `DocfyUiModule.setup(mountPath, app, options?)`
|
|
521
521
|
|
|
522
|
-
Serves [`docfy-ui`](https://www.npmjs.com/package/docfy-ui) — the AI-first documentation UI companion to this package — at `mountPath`, the same role `SwaggerModule.setup()` + `swagger-ui-express` play for raw Swagger UI.
|
|
522
|
+
Serves [`docfy-ui`](https://www.npmjs.com/package/docfy-ui) — the AI-first documentation UI companion to this package — at `mountPath`, the same role `SwaggerModule.setup()` + `swagger-ui-express` play for raw Swagger UI. Works on both Express (`@nestjs/platform-express`) and Fastify (`@nestjs/platform-fastify`) apps. On Fastify, static asset serving needs the optional peer dependency [`@fastify/static`](https://www.npmjs.com/package/@fastify/static) (`npm install @fastify/static`) — the same package `@nestjs/swagger` itself relies on for Fastify Swagger UI support.
|
|
523
523
|
|
|
524
524
|
```ts
|
|
525
525
|
import { NestFactory } from '@nestjs/core';
|
|
@@ -556,6 +556,8 @@ DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });
|
|
|
556
556
|
|
|
557
557
|
Call this **before** `SwaggerModule.setup()`: Express resolves routes in registration order, so the static, patched document takes precedence over the live one for any request to `/api-json`.
|
|
558
558
|
|
|
559
|
+
> **Fastify caveat**: `SwaggerModule.setup()` also registers its own `/api-json` route by default. On Express, whichever route is registered first silently wins. On Fastify, registering the same exact route twice throws `FST_ERR_DUPLICATED_ROUTE` at startup instead — registration order does not save you. When using `staticSpecPath` together with Fastify, point `SwaggerModule.setup()` at a different `jsonDocumentUrl`, or pass `{ raw: false }`, so it doesn't also claim `/api-json`.
|
|
560
|
+
>
|
|
559
561
|
> **Caveat**: `docfy-ui` renders with React Router's `BrowserRouter` and no configurable `basename` yet, so deep client-side routes (e.g. reloading an endpoint's detail page directly) only resolve correctly when `mountPath` is `/` — the application's root. Mounting elsewhere (e.g. `/docs`) still serves the UI and its initial load works fine; in-app navigation to a specific endpoint and then reloading that URL does not yet work at a non-root mount path.
|
|
560
562
|
|
|
561
563
|
## Interface-typed DTOs
|
|
@@ -1,13 +1,25 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Minimal structural shape of what `DocfyUiModule.setup()` needs from a
|
|
3
|
-
* NestJS
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
|
|
7
|
-
|
|
3
|
+
* NestJS HTTP adapter (`app.getHttpAdapter()`). Matches `@nestjs/common`'s
|
|
4
|
+
* real `HttpServer` interface, so every real `INestApplication` /
|
|
5
|
+
* `NestFastifyApplication` satisfies this with no extra work.
|
|
6
|
+
*/
|
|
7
|
+
export interface DocfyUiHttpAdapter {
|
|
8
|
+
getType(): string;
|
|
9
|
+
getInstance(): unknown;
|
|
10
|
+
get(path: string, handler: (req: unknown, res: unknown) => unknown): unknown;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Minimal structural shape of what `DocfyUiModule.setup()` needs from a
|
|
14
|
+
* NestJS application instance — just enough to register middleware/routes.
|
|
15
|
+
* Deliberately not typed as `INestApplication` so this file doesn't pull
|
|
16
|
+
* `@nestjs/common`'s full surface into a narrow concern, and not typed as
|
|
17
|
+
* `express.Application` so consumers don't need `@types/express` just to
|
|
18
|
+
* call this function.
|
|
8
19
|
*/
|
|
9
20
|
export interface DocfyUiSetupTarget {
|
|
10
21
|
use(...args: unknown[]): unknown;
|
|
22
|
+
getHttpAdapter(): DocfyUiHttpAdapter;
|
|
11
23
|
}
|
|
12
24
|
export interface DocfyUiSetupOptions {
|
|
13
25
|
/**
|
|
@@ -22,10 +34,13 @@ export interface DocfyUiSetupOptions {
|
|
|
22
34
|
* npx nestjs-docfy patch-spec --spec <url-or-path> --out <path>
|
|
23
35
|
*
|
|
24
36
|
* Call `DocfyUiModule.setup()` with this option *before*
|
|
25
|
-
* `SwaggerModule.setup()` in your bootstrap — Express
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
37
|
+
* `SwaggerModule.setup()` in your bootstrap — on Express this ordering
|
|
38
|
+
* guarantees the static, patched document takes precedence for any
|
|
39
|
+
* request to `/api-json`. On Fastify, registering `SwaggerModule.setup()`
|
|
40
|
+
* with its default `/api-json` route alongside this option throws
|
|
41
|
+
* `FST_ERR_DUPLICATED_ROUTE` at startup instead — point
|
|
42
|
+
* `SwaggerModule.setup()` at a different `jsonDocumentUrl` (or pass
|
|
43
|
+
* `{ raw: false }`) when using `staticSpecPath` on a Fastify app.
|
|
29
44
|
*/
|
|
30
45
|
staticSpecPath?: string;
|
|
31
46
|
}
|
|
@@ -33,7 +48,8 @@ export interface DocfyUiSetupOptions {
|
|
|
33
48
|
* Serves the published `docfy-ui` package's static build at `mountPath`,
|
|
34
49
|
* giving a `nestjs-docfy`-equipped app a documentation UI by default —
|
|
35
50
|
* the same role `SwaggerModule.setup()` + `swagger-ui-express` play for
|
|
36
|
-
* raw Swagger UI, but for `docfy-ui`.
|
|
51
|
+
* raw Swagger UI, but for `docfy-ui`. Works on both Express and Fastify
|
|
52
|
+
* Nest apps.
|
|
37
53
|
*
|
|
38
54
|
* Deep client-side routes (e.g. reloading `/docs/users/findAllUsers`
|
|
39
55
|
* directly) resolve correctly at any `mountPath`: this injects a `<base>`
|
package/dist/docfy-ui.module.js
CHANGED
|
@@ -37,11 +37,22 @@ exports.DocfyUiModule = void 0;
|
|
|
37
37
|
const fs = __importStar(require("fs"));
|
|
38
38
|
const path = __importStar(require("path"));
|
|
39
39
|
const express = __importStar(require("express"));
|
|
40
|
+
function loadFastifyStatic() {
|
|
41
|
+
try {
|
|
42
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
43
|
+
return require('@fastify/static');
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
throw new Error("DocfyUiModule.setup(): serving docfy-ui on a Fastify-based Nest app requires " +
|
|
47
|
+
"the optional peer dependency '@fastify/static'. Install it with `npm install @fastify/static`.");
|
|
48
|
+
}
|
|
49
|
+
}
|
|
40
50
|
/**
|
|
41
51
|
* Serves the published `docfy-ui` package's static build at `mountPath`,
|
|
42
52
|
* giving a `nestjs-docfy`-equipped app a documentation UI by default —
|
|
43
53
|
* the same role `SwaggerModule.setup()` + `swagger-ui-express` play for
|
|
44
|
-
* raw Swagger UI, but for `docfy-ui`.
|
|
54
|
+
* raw Swagger UI, but for `docfy-ui`. Works on both Express and Fastify
|
|
55
|
+
* Nest apps.
|
|
45
56
|
*
|
|
46
57
|
* Deep client-side routes (e.g. reloading `/docs/users/findAllUsers`
|
|
47
58
|
* directly) resolve correctly at any `mountPath`: this injects a `<base>`
|
|
@@ -52,11 +63,13 @@ const express = __importStar(require("express"));
|
|
|
52
63
|
*/
|
|
53
64
|
class DocfyUiModule {
|
|
54
65
|
static setup(mountPath, app, options = {}) {
|
|
66
|
+
const httpAdapter = app.getHttpAdapter();
|
|
67
|
+
const isFastify = httpAdapter.getType() === 'fastify';
|
|
55
68
|
if (options.staticSpecPath) {
|
|
56
69
|
const specJson = fs.readFileSync(options.staticSpecPath, 'utf8');
|
|
57
|
-
|
|
58
|
-
res.
|
|
59
|
-
res.
|
|
70
|
+
httpAdapter.get('/api-json', (_req, res) => {
|
|
71
|
+
res.type('application/json');
|
|
72
|
+
res.send(specJson);
|
|
60
73
|
});
|
|
61
74
|
}
|
|
62
75
|
const indexHtmlPath = require.resolve('docfy-ui/dist/index.html');
|
|
@@ -65,13 +78,36 @@ class DocfyUiModule {
|
|
|
65
78
|
const indexHtml = fs
|
|
66
79
|
.readFileSync(indexHtmlPath, 'utf8')
|
|
67
80
|
.replace('<head>', `<head>\n <base href="${basePath}" />\n <script>window.__DOCFY_BASE_PATH__ = ${JSON.stringify(basePath)};</script>`);
|
|
81
|
+
if (isFastify) {
|
|
82
|
+
const fastifyStatic = loadFastifyStatic();
|
|
83
|
+
const instance = httpAdapter.getInstance();
|
|
84
|
+
instance.register((scoped, _opts, done) => {
|
|
85
|
+
scoped.register(fastifyStatic, {
|
|
86
|
+
root: uiDir,
|
|
87
|
+
// `wildcard: false` is required by @fastify/static for a scoped
|
|
88
|
+
// setNotFoundHandler to combine correctly with static serving.
|
|
89
|
+
wildcard: false,
|
|
90
|
+
// `index: false` so directory requests (e.g. `GET /docs/`) fall
|
|
91
|
+
// through to the not-found handler below instead of
|
|
92
|
+
// @fastify/static serving the un-patched index.html straight
|
|
93
|
+
// off disk.
|
|
94
|
+
index: false,
|
|
95
|
+
decorateReply: false,
|
|
96
|
+
});
|
|
97
|
+
scoped.setNotFoundHandler((_req, reply) => {
|
|
98
|
+
reply.type('text/html').send(indexHtml);
|
|
99
|
+
});
|
|
100
|
+
done();
|
|
101
|
+
}, { prefix: mountPath });
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
68
104
|
// `index: false` so directory requests (e.g. `GET /docs/`) fall through
|
|
69
105
|
// to the catch-all below instead of express.static serving the
|
|
70
106
|
// un-patched index.html straight off disk.
|
|
71
107
|
app.use(mountPath, express.static(uiDir, { index: false }));
|
|
72
108
|
app.use(mountPath, (_req, res) => {
|
|
73
|
-
res.
|
|
74
|
-
res.
|
|
109
|
+
res.type('text/html');
|
|
110
|
+
res.send(indexHtml);
|
|
75
111
|
});
|
|
76
112
|
}
|
|
77
113
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docfy-ui.module.js","sourceRoot":"","sources":["../src/docfy-ui.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAC7B,iDAAmC;
|
|
1
|
+
{"version":3,"file":"docfy-ui.module.js","sourceRoot":"","sources":["../src/docfy-ui.module.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -3,4 +3,4 @@ export { docs, DocsConfig } from './docs';
|
|
|
3
3
|
export { DocfyModule, DocfyModuleOptions } from './docfy.module';
|
|
4
4
|
export { attachTagGroups } from './attach-tag-groups';
|
|
5
5
|
export { TagGroup } from './tag-group-registry';
|
|
6
|
-
export { DocfyUiModule, DocfyUiSetupTarget, DocfyUiSetupOptions } from './docfy-ui.module';
|
|
6
|
+
export { DocfyUiModule, DocfyUiSetupTarget, DocfyUiSetupOptions, DocfyUiHttpAdapter, } from './docfy-ui.module';
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAA+D;AAAtD,+GAAA,QAAQ,OAAA;AAAE,mHAAA,YAAY,OAAA;AAC/B,+BAA0C;AAAjC,4FAAA,IAAI,OAAA;AACb,+CAAiE;AAAxD,2GAAA,WAAW,OAAA;AACpB,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AAExB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAA+D;AAAtD,+GAAA,QAAQ,OAAA;AAAE,mHAAA,YAAY,OAAA;AAC/B,+BAA0C;AAAjC,4FAAA,IAAI,OAAA;AACb,+CAAiE;AAAxD,2GAAA,WAAW,OAAA;AACpB,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AAExB,qDAK2B;AAJzB,gHAAA,aAAa,OAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nestjs-docfy",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Keep your NestJS controllers clean — Swagger docs live in a separate companion file by naming convention",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -68,17 +68,26 @@
|
|
|
68
68
|
},
|
|
69
69
|
"license": "MIT",
|
|
70
70
|
"peerDependencies": {
|
|
71
|
+
"@fastify/static": "^8.0.0 || ^9.0.0",
|
|
71
72
|
"@nestjs/common": ">=9.0.0",
|
|
72
73
|
"@nestjs/swagger": ">=6.0.0",
|
|
73
74
|
"reflect-metadata": "^0.1.13 || ^0.2.0"
|
|
74
75
|
},
|
|
76
|
+
"peerDependenciesMeta": {
|
|
77
|
+
"@fastify/static": {
|
|
78
|
+
"optional": true
|
|
79
|
+
}
|
|
80
|
+
},
|
|
75
81
|
"devDependencies": {
|
|
82
|
+
"@fastify/static": "^9.3.0",
|
|
76
83
|
"@nestjs/common": "^11.0.0",
|
|
77
84
|
"@nestjs/core": "^11.0.0",
|
|
85
|
+
"@nestjs/platform-fastify": "^11.1.28",
|
|
78
86
|
"@nestjs/swagger": "^11.0.0",
|
|
79
87
|
"@types/express": "^5.0.0",
|
|
80
88
|
"@types/jest": "^29.5.14",
|
|
81
89
|
"@types/node": "^22.0.0",
|
|
90
|
+
"fastify": "^5.10.0",
|
|
82
91
|
"jest": "^29.7.0",
|
|
83
92
|
"reflect-metadata": "^0.2.2",
|
|
84
93
|
"ts-jest": "^29.2.5",
|