@vnphu/nestjs-api-explorer 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# nestjs-api-docs
+
+An in-app API explorer for NestJS — like Postman, but embedded directly into your application. Zero external dependencies, dark-themed, and auto-disabled in production.
+
+## Features
+
+- **Route auto-discovery** — scans the live Express router, no decorators needed
+- **Full request builder** — path params, query params, headers, auth, and body
+- **Auth support** — Bearer Token, Basic Auth, API Key (header or query)
+- **Body types** — JSON (with formatter), Form-encoded, Plain text
+- **Response viewer** — syntax-highlighted JSON, status badge, timing, response headers
+- **Resizable panels** — drag-to-resize sidebar and request/response split
+- **Auto-disabled in production** — safe to leave in your codebase
+
+## Installation
+
+```bash
+npm install nestjs-api-docs
+# or
+yarn add nestjs-api-docs
+# or
+pnpm add nestjs-api-docs
+```
+
+## Usage
+
+Register the module in your `AppModule`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ApiExplorerModule } from 'nestjs-api-docs';
+
+@Module({
+  imports: [
+    ApiExplorerModule.register({
+      path: 'api-explorer',   // UI available at GET /api-explorer
+      title: 'My API',
+      enabled: true,           // auto-false in production
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Then start your app and visit:
+
+```
+http://localhost:3000/api-explorer
+```
+
+## Options
+
+| Option    | Type      | Default          | Description                                                     |
+|-----------|-----------|------------------|-----------------------------------------------------------------|
+| `path`    | `string`  | `'api-explorer'` | URL path prefix where the explorer is served                    |
+| `title`   | `string`  | `'API Explorer'` | Title shown in the browser tab and UI header                    |
+| `enabled` | `boolean` | `true`           | Explicitly enable/disable. Always disabled when `NODE_ENV=production` |
+
+## Endpoints
+
+Once registered, two endpoints are added:
+
+| Method | Path                   | Description                          |
+|--------|------------------------|--------------------------------------|
+| `GET`  | `/{path}`              | Serves the explorer HTML UI          |
+| `GET`  | `/{path}/routes`       | Returns discovered routes as JSON    |
+
+### Route response format
+
+```json
+[
+  {
+    "method": "GET",
+    "path": "/users",
+    "params": []
+  },
+  {
+    "method": "GET",
+    "path": "/users/:id",
+    "params": ["id"]
+  }
+]
+```
+
+## Using the UI
+
+1. **Select a route** from the sidebar (use the search bar to filter)
+2. **Fill in parameters** — path params are auto-detected and shown first
+3. **Set headers / auth / body** using the tabs in the request panel
+4. **Click Send** (or press `Ctrl+Enter` / `Cmd+Enter`)
+5. **Inspect the response** — body with JSON highlighting, status, timing, and headers
+
+### Auth tab
+
+| Type          | Description                                              |
+|---------------|----------------------------------------------------------|
+| None          | No Authorization header                                  |
+| Bearer Token  | Adds `Authorization: Bearer <token>`                     |
+| Basic Auth    | Adds `Authorization: Basic <base64(user:pass)>`          |
+| API Key       | Adds a custom key to a header or as a query parameter    |
+
+### Body tab
+
+| Type   | Content-Type                        |
+|--------|-------------------------------------|
+| None   | No body sent                        |
+| JSON   | `application/json` + Format button  |
+| Form   | `application/x-www-form-urlencoded` |
+| Text   | `text/plain`                        |
+
+## Peer dependencies
+
+```json
+{
+  "@nestjs/common": ">=9.0.0",
+  "@nestjs/core": ">=9.0.0"
+}
+```
+
+## How it works
+
+`ApiExplorerService` uses NestJS's `HttpAdapterHost` to access the underlying Express app instance and traverses `app._router.stack` to discover all registered routes at request time. This means the route list is always up-to-date with whatever is actually mounted on the Express router.
+
+## Production safety
+
+The module automatically returns an empty `DynamicModule` (no controllers, no providers) when `NODE_ENV === 'production'`, so there is no runtime overhead and no routes are exposed.
+
+You can also disable it explicitly:
+
+```typescript
+ApiExplorerModule.register({ enabled: false })
+```
+
+## License
+
+MIT

package/dist/api-explorer.controller.d.ts

@@ -0,0 +1,16 @@
+import { ResolvedApiExplorerOptions } from './api-explorer.module';
+import { ApiExplorerService } from './api-explorer.service';
+/**
+ * Creates an ApiExplorer controller bound to the given path at runtime.
+ * Using a factory lets us set @Controller(path) dynamically from options
+ * without requiring decorators at compile time.
+ */
+export declare function createApiExplorerController(explorerPath: string): {
+    new (service: ApiExplorerService, options: ResolvedApiExplorerOptions): {
+        readonly service: ApiExplorerService;
+        readonly options: ResolvedApiExplorerOptions;
+        getUi(res: any): void;
+        getRoutes(req: any): import("./api-explorer.service").RouteInfo[];
+    };
+};
+//# sourceMappingURL=api-explorer.controller.d.ts.map

package/dist/api-explorer.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-explorer.controller.d.ts","sourceRoot":"","sources":["../src/api-explorer.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM;kBAIjC,kBAAkB,WAElB,0BAA0B;0BAF1B,kBAAkB;0BAElB,0BAA0B;mBAInC,GAAG,GAAG,IAAI;uBAON,GAAG;;EAM5B"}

package/dist/api-explorer.controller.js

@@ -0,0 +1,61 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiExplorerController = createApiExplorerController;
+const common_1 = require("@nestjs/common");
+const api_explorer_module_1 = require("./api-explorer.module");
+const api_explorer_service_1 = require("./api-explorer.service");
+const api_explorer_html_1 = require("./api-explorer.html");
+/**
+ * Creates an ApiExplorer controller bound to the given path at runtime.
+ * Using a factory lets us set @Controller(path) dynamically from options
+ * without requiring decorators at compile time.
+ */
+function createApiExplorerController(explorerPath) {
+    let ApiExplorerController = class ApiExplorerController {
+        constructor(service, options) {
+            this.service = service;
+            this.options = options;
+        }
+        getUi(res) {
+            const html = (0, api_explorer_html_1.getExplorerHtml)(this.options);
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.send(html);
+        }
+        getRoutes(req) {
+            return this.service.getRoutes(req.app);
+        }
+    };
+    __decorate([
+        (0, common_1.Get)(),
+        __param(0, (0, common_1.Res)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", void 0)
+    ], ApiExplorerController.prototype, "getUi", null);
+    __decorate([
+        (0, common_1.Get)('routes'),
+        __param(0, (0, common_1.Req)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", void 0)
+    ], ApiExplorerController.prototype, "getRoutes", null);
+    ApiExplorerController = __decorate([
+        (0, common_1.Controller)(explorerPath),
+        __param(1, (0, common_1.Inject)(api_explorer_module_1.API_EXPLORER_OPTIONS)),
+        __metadata("design:paramtypes", [api_explorer_service_1.ApiExplorerService, Object])
+    ], ApiExplorerController);
+    return ApiExplorerController;
+}
+//# sourceMappingURL=api-explorer.controller.js.map

package/dist/api-explorer.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-explorer.controller.js","sourceRoot":"","sources":["../src/api-explorer.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAUA,kEAuBC;AAjCD,2CAAmE;AACnE,+DAAyF;AACzF,iEAA4D;AAC5D,2DAAsD;AAEtD;;;;GAIG;AACH,SAAgB,2BAA2B,CAAC,YAAoB;IAC9D,IACM,qBAAqB,GAD3B,MACM,qBAAqB;QACzB,YACkB,OAA2B,EAE3B,OAAmC;YAFnC,YAAO,GAAP,OAAO,CAAoB;YAE3B,YAAO,GAAP,OAAO,CAA4B;QAClD,CAAC;QAGJ,KAAK,CAAQ,GAAQ;YACnB,MAAM,IAAI,GAAG,IAAA,mCAAe,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3C,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC;YAC1D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAGD,SAAS,CAAQ,GAAQ;YACvB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzC,CAAC;KACF,CAAA;IAVC;QADC,IAAA,YAAG,GAAE;QACC,WAAA,IAAA,YAAG,GAAE,CAAA;;;;sDAIX;IAGD;QADC,IAAA,YAAG,EAAC,QAAQ,CAAC;QACH,WAAA,IAAA,YAAG,GAAE,CAAA;;;;0DAEf;IAjBG,qBAAqB;QAD1B,IAAA,mBAAU,EAAC,YAAY,CAAC;QAIpB,WAAA,IAAA,eAAM,EAAC,0CAAoB,CAAC,CAAA;yCADJ,yCAAkB;OAFzC,qBAAqB,CAkB1B;IAED,OAAO,qBAAqB,CAAC;AAC/B,CAAC"}

package/dist/api-explorer.html.d.ts

@@ -0,0 +1,3 @@
+import { ResolvedApiExplorerOptions } from './api-explorer.module';
+export declare function getExplorerHtml(options: ResolvedApiExplorerOptions): string;
+//# sourceMappingURL=api-explorer.html.d.ts.map

package/dist/api-explorer.html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-explorer.html.d.ts","sourceRoot":"","sources":["../src/api-explorer.html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAEnE,wBAAgB,eAAe,CAAC,OAAO,EAAE,0BAA0B,GAAG,MAAM,CAsiC3E"}