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 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. Built on Express's static-file middleware directly, so it expects an Express-based Nest app (the default `@nestjs/platform-express` adapter) — Fastify isn't supported yet.
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 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.
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 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`.
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>`
@@ -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
- app.use('/api-json', (_req, res) => {
58
- res.setHeader('Content-Type', 'application/json');
59
- res.end(specJson);
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.setHeader('Content-Type', 'text/html');
74
- res.end(indexHtml);
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;AAmCnC;;;;;;;;;;;;GAYG;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;QAC1C,MAAM,QAAQ,GAAG,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC;QAC/E,MAAM,SAAS,GAAG,EAAE;aACjB,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC;aACnC,OAAO,CACN,QAAQ,EACR,2BAA2B,QAAQ,kDAAkD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,YAAY,CAC1H,CAAC;QAEJ,wEAAwE;QACxE,+DAA+D;QAC/D,2CAA2C;QAC3C,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5D,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAqB,EAAE,GAAqB,EAAE,EAAE;YAClE,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;YAC3C,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAjCD,sCAiCC"}
1
+ {"version":3,"file":"docfy-ui.module.js","sourceRoot":"","sources":["../src/docfy-ui.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAC7B,iDAAmC;AAuDnC,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,+EAA+E;YAC7E,gGAAgG,CACnG,CAAC;IACJ,CAAC;AACH,CAAC;AAkBD;;;;;;;;;;;;;GAaG;AACH,MAAa,aAAa;IACxB,MAAM,CAAC,KAAK,CACV,SAAiB,EACjB,GAAuB,EACvB,UAA+B,EAAE;QAEjC,MAAM,WAAW,GAAG,GAAG,CAAC,cAAc,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,SAAS,CAAC;QAEtD,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;YACjE,WAAW,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAa,EAAE,GAAQ,EAAE,EAAE;gBACvD,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;gBAC7B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,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;QAC1C,MAAM,QAAQ,GAAG,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC;QAC/E,MAAM,SAAS,GAAG,EAAE;aACjB,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC;aACnC,OAAO,CACN,QAAQ,EACR,2BAA2B,QAAQ,kDAAkD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,YAAY,CAC1H,CAAC;QAEJ,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,aAAa,GAAG,iBAAiB,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAyB,CAAC;YAClE,QAAQ,CAAC,QAAQ,CACf,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE;oBAC7B,IAAI,EAAE,KAAK;oBACX,gEAAgE;oBAChE,+DAA+D;oBAC/D,QAAQ,EAAE,KAAK;oBACf,gEAAgE;oBAChE,oDAAoD;oBACpD,6DAA6D;oBAC7D,YAAY;oBACZ,KAAK,EAAE,KAAK;oBACZ,aAAa,EAAE,KAAK;iBACrB,CAAC,CAAC;gBACH,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;oBACxC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC1C,CAAC,CAAC,CAAC;gBACH,IAAI,EAAE,CAAC;YACT,CAAC,EACD,EAAE,MAAM,EAAE,SAAS,EAAE,CACtB,CAAC;YACF,OAAO;QACT,CAAC;QAED,wEAAwE;QACxE,+DAA+D;QAC/D,2CAA2C;QAC3C,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5D,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAqB,EAAE,GAAqB,EAAE,EAAE;YAClE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACtB,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AA/DD,sCA+DC"}
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,qDAA2F;AAAlF,gHAAA,aAAa,OAAA"}
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.6",
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",