@application-kit/bootstrap 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @application-kit/bootstrap
 
+## 0.4.0
+
+### Minor Changes
+
+- 9ee9bfa: Вход `@application-kit/bootstrap/swagger`: `setupSwagger(app, { include, path?, version? })` публикует документ OpenAPI,
+  только если `SWAGGER_ENABLED` включён явно. `@nestjs/swagger` — optional peer, его тянет только этот вход.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # @application-kit/bootstrap
 
 Бутстрап процессов NestJS: web на Fastify с периметром, consumer с сервером метрик и CLI на nestjs-console. Состав
-модулей, Swagger и хуки метрик знает приложение: пакет собирает процесс из его корневого модуля и опций. Порт, число
+модулей, контроллеры документа Swagger и хуки метрик знает приложение: пакет собирает процесс из его корневого модуля и опций. Порт, число
 прокси и порт метрик — переменные окружения контракта чарта; невалидное значение роняет старт.
 
 ## Установка
@@ -21,6 +21,7 @@ Peer-зависимости — `@nestjs/common`, `@nestjs/core`, `nestjs-pino`;
 | `@application-kit/bootstrap/web` | `webBootstrap`, `createFastifyApplication` — web-процесс на Fastify | `@nestjs/platform-fastify`, `@fastify/cookie`, `class-validator`, `class-transformer`, `@opentelemetry/api`, `@libs-for-dev/nestjs-config-module` |
 | `@application-kit/bootstrap/consumer` | `consumerBootstrap` — процесс-консьюмер без HTTP-слоя | `class-validator`, `class-transformer`, `@libs-for-dev/nestjs-config-module` |
 | `@application-kit/bootstrap/cli` | `cliBootstrap` — CLI-процесс | `nestjs-console` |
+| `@application-kit/bootstrap/swagger` | `setupSwagger` — документ OpenAPI web-процесса по выключателю | `@nestjs/swagger`, `class-validator`, `class-transformer`, `@libs-for-dev/nestjs-config-module` |
 
 Корневого входа нет: web-процессу `nestjs-console` не нужен, CLI — Fastify.
 
@@ -31,8 +32,9 @@ Peer-зависимости — `@nestjs/common`, `@nestjs/core`, `nestjs-pino`;
 | `PORT` | web | `3000` | порт `listen` на `0.0.0.0` |
 | `TRUST_PROXY_HOPS` | web | `0` | сколько прокси перед приложением доверенные; `0` — только сокет |
 | `METRICS_PORT` | consumer | `3001` | порт отдельного сервера `/metrics` |
+| `SWAGGER_ENABLED` | web | `false` | публиковать ли документ `setupSwagger`; выключают `false`, `0` и пустая строка |
 
-Значение — целое не меньше 0 (порт — не больше 65535). Иное (`abc`, `1.5`, `-1`) — `ClassValidationError` с именем
+Значение числовых переменных — целое не меньше 0 (порт — не больше 65535). Иное (`abc`, `1.5`, `-1`) — `ClassValidationError` с именем
 переменной до создания приложения: `Number('abc')` дал бы `NaN`, и доверенных прокси молча стало бы ноль.
 
 ## Web
@@ -82,6 +84,22 @@ await app.listen(port, '0.0.0.0')
 | `cookie` | `{}` | опции `@fastify/cookie`; `false` — плагин не регистрируется |
 | `configure` | — | `(app) => void`, зовётся после хука request-id, до интерцептора и пайпа |
 
+## Swagger
+
+```ts
+import { setupSwagger } from '@application-kit/bootstrap/swagger'
+
+const options = {
+  configure: (app) => {
+    setupSwagger(app, { include: [HealthHttpModule, MetricsHttpModule] })
+  },
+} satisfies FastifyApplicationOptionsInterface
+```
+
+Документ описывает всю серверную поверхность и аутентификации не требует, поэтому без `SWAGGER_ENABLED` он не
+публикуется. В документ попадают контроллеры модулей из `include`, `operationId` — имя метода. UI отдаётся по `path`
+(по умолчанию `swagger`), JSON — по `<path>-json`, версия в `info` — `version` (по умолчанию `1.0`).
+
 ## Consumer
 
 ```ts

package/dist/cjs/swagger/index.d.ts

@@ -0,0 +1,3 @@
+export * from './setup-swagger.js';
+export * from './swagger-options.interface.js';
+export * from './swagger.environment.js';

package/dist/cjs/swagger/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./setup-swagger.js"), exports);
+__exportStar(require("./swagger-options.interface.js"), exports);
+__exportStar(require("./swagger.environment.js"), exports);

package/dist/cjs/swagger/setup-swagger.d.ts

@@ -0,0 +1,3 @@
+import type { INestApplication } from '@nestjs/common';
+import type { SwaggerOptionsInterface } from './swagger-options.interface.js';
+export declare const setupSwagger: (app: INestApplication, options: SwaggerOptionsInterface) => void;

package/dist/cjs/swagger/setup-swagger.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSwagger = void 0;
+const nestjs_config_module_1 = require("@libs-for-dev/nestjs-config-module");
+const swagger_1 = require("@nestjs/swagger");
+const node_process_1 = __importDefault(require("node:process"));
+const swagger_environment_js_1 = require("./swagger.environment.js");
+const DEFAULT_PATH = 'swagger';
+const DEFAULT_VERSION = '1.0';
+const setupSwagger = (app, options) => {
+    const environment = (0, nestjs_config_module_1.exposeObjectWithValidation)(node_process_1.default.env, swagger_environment_js_1.SwaggerEnvironment);
+    if (!environment.SWAGGER_ENABLED) {
+        return;
+    }
+    const document = swagger_1.SwaggerModule.createDocument(app, new swagger_1.DocumentBuilder().setVersion(options.version ?? DEFAULT_VERSION)
+        .build(), {
+        include: options.include,
+        operationIdFactory: (_controllerKey, methodKey) => methodKey,
+    });
+    swagger_1.SwaggerModule.setup(options.path ?? DEFAULT_PATH, app, document);
+};
+exports.setupSwagger = setupSwagger;

package/dist/cjs/swagger/swagger-options.interface.d.ts

@@ -0,0 +1,6 @@
+import type { Type } from '@nestjs/common';
+export interface SwaggerOptionsInterface {
+    include: Type[];
+    path?: string;
+    version?: string;
+}

package/dist/cjs/swagger/swagger-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/swagger/swagger.environment.d.ts

@@ -0,0 +1,3 @@
+export declare class SwaggerEnvironment {
+    SWAGGER_ENABLED: boolean;
+}

package/dist/cjs/swagger/swagger.environment.js

@@ -0,0 +1,25 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerEnvironment = void 0;
+const nestjs_config_module_1 = require("@libs-for-dev/nestjs-config-module");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+class SwaggerEnvironment {
+    SWAGGER_ENABLED = false;
+}
+exports.SwaggerEnvironment = SwaggerEnvironment;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsBoolean)(),
+    (0, nestjs_config_module_1.ParseBoolean)(),
+    __metadata("design:type", Object)
+], SwaggerEnvironment.prototype, "SWAGGER_ENABLED", void 0);

package/dist/esm/swagger/index.d.ts

@@ -0,0 +1,3 @@
+export * from './setup-swagger.js';
+export * from './swagger-options.interface.js';
+export * from './swagger.environment.js';

package/dist/esm/swagger/index.js

@@ -0,0 +1,3 @@
+export * from './setup-swagger.js';
+export * from './swagger-options.interface.js';
+export * from './swagger.environment.js';

package/dist/esm/swagger/setup-swagger.d.ts

@@ -0,0 +1,3 @@
+import type { INestApplication } from '@nestjs/common';
+import type { SwaggerOptionsInterface } from './swagger-options.interface.js';
+export declare const setupSwagger: (app: INestApplication, options: SwaggerOptionsInterface) => void;

package/dist/esm/swagger/setup-swagger.js

@@ -0,0 +1,18 @@
+import { exposeObjectWithValidation } from '@libs-for-dev/nestjs-config-module';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import process from 'node:process';
+import { SwaggerEnvironment } from './swagger.environment.js';
+const DEFAULT_PATH = 'swagger';
+const DEFAULT_VERSION = '1.0';
+export const setupSwagger = (app, options) => {
+    const environment = exposeObjectWithValidation(process.env, SwaggerEnvironment);
+    if (!environment.SWAGGER_ENABLED) {
+        return;
+    }
+    const document = SwaggerModule.createDocument(app, new DocumentBuilder().setVersion(options.version ?? DEFAULT_VERSION)
+        .build(), {
+        include: options.include,
+        operationIdFactory: (_controllerKey, methodKey) => methodKey,
+    });
+    SwaggerModule.setup(options.path ?? DEFAULT_PATH, app, document);
+};

package/dist/esm/swagger/swagger-options.interface.d.ts

@@ -0,0 +1,6 @@
+import type { Type } from '@nestjs/common';
+export interface SwaggerOptionsInterface {
+    include: Type[];
+    path?: string;
+    version?: string;
+}

package/dist/esm/swagger/swagger-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/swagger/swagger.environment.d.ts

@@ -0,0 +1,3 @@
+export declare class SwaggerEnvironment {
+    SWAGGER_ENABLED: boolean;
+}

package/dist/esm/swagger/swagger.environment.js

@@ -0,0 +1,21 @@
+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);
+};
+import { ParseBoolean } from '@libs-for-dev/nestjs-config-module';
+import { Expose } from 'class-transformer';
+import { IsBoolean } from 'class-validator';
+export class SwaggerEnvironment {
+    SWAGGER_ENABLED = false;
+}
+__decorate([
+    Expose(),
+    IsBoolean(),
+    ParseBoolean(),
+    __metadata("design:type", Object)
+], SwaggerEnvironment.prototype, "SWAGGER_ENABLED", void 0);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@application-kit/bootstrap",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Бутстрап процессов NestJS: web на Fastify с периметром (доверенные прокси по хопам, request-id в каждом ответе, cookie, ValidationPipe с плоским списком ошибок, graceful shutdown), consumer с сервером метрик, CLI на nestjs-console с логгером pino; порты и прокси — из валидированного окружения",
   "keywords": [
     "bootstrap",
     "fastify",
     "nestjs",
-    "nestjs-console"
+    "nestjs-console",
+    "swagger"
   ],
   "homepage": "https://gitlab.com/application-kit/application-kit/-/tree/main/packages/bootstrap",
   "bugs": "https://gitlab.com/application-kit/application-kit/-/issues",
@@ -43,6 +44,16 @@
       }
     },
     "./package.json": "./package.json",
+    "./swagger": {
+      "import": {
+        "types": "./dist/esm/swagger/index.d.ts",
+        "default": "./dist/esm/swagger/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/swagger/index.d.ts",
+        "default": "./dist/cjs/swagger/index.js"
+      }
+    },
     "./web": {
       "import": {
         "types": "./dist/esm/web/index.d.ts",
@@ -61,7 +72,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cli && node ../../scripts/barrels.mjs create ./src/consumer && node ../../scripts/barrels.mjs create ./src/web && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cli && node ../../scripts/barrels.mjs create ./src/consumer && node ../../scripts/barrels.mjs create ./src/swagger && node ../../scripts/barrels.mjs create ./src/web && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
     "lint:tsc": "tsc --noEmit --pretty --project .",
     "test:mutation": "stryker run",
     "test:unit": "vitest run"
@@ -75,6 +86,7 @@
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",
     "@nestjs/platform-fastify": "^11.2.7",
+    "@nestjs/swagger": "^11.4.8",
     "@opentelemetry/api": "^1.9.1",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
@@ -96,6 +108,7 @@
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0 || ^12.0.0",
     "@opentelemetry/api": "^1.9.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
@@ -112,6 +125,9 @@
     "@nestjs/platform-fastify": {
       "optional": true
     },
+    "@nestjs/swagger": {
+      "optional": true
+    },
     "@opentelemetry/api": {
       "optional": true
     },