@l337quez/nest-swagger-zen 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "workbench.colorCustomizations": {}
+}

package/README.md

@@ -0,0 +1,105 @@
+# Nest Swagger Zen 🐼
+
+![Nest Swagger Zen Portada](./assets/nest-swagger-zen.png)
+
+Una librería genérica y estilizada para NestJS que te ayudará a limpiar tus controladores y modularizar la documentación de tu API de forma elegante. Con `nest-swagger-zen`, ya no tendrás que definir archivos pesados de configuración llenos de esquemas JSON.
+
+## Características ✨
+- **100% Nest-Ready**: Utiliza las convenciones nativas de `@nestjs/swagger` y `applyDecorators`.
+- **Limpieza visual**: Configura `ApiOperation`, `ApiResponse`, `ApiBody` y parámetros paginados en un **solo** bloque de configuración limpio y fuertemente tipado.
+- **Adiós JSON schemas manuales**: Al usar DTOs, NestJS se encarga de autogenerar los JSON.
+
+## Instalación 📦
+
+Al no estar en el registro público todavía, puedes instalar la librería en tus proyectos Nest referenciando rutas relativas o absolutas:
+
+```bash
+npm install nest-swagger-zen
+```
+
+
+## Uso 🚀
+
+### 1. Reemplaza tus JSON manuales con Clases de Datos (DTOs o Modelos)
+En lugar de crear constantes masivas que exportan `schema: { type: 'object' ... }`, utiliza clases junto con los decoradores centralizados de esta librería. 
+
+> *Nota: Swagger es agnóstico a la arquitectura. Puedes usar `@ZenProperty()` tanto en tus **DTOs** como directamente en los **Modelos o Entidades** de tu base de datos (Mongoose, TypeORM, etc).*
+
+Crea tus clases para Request (**Body**) o para la respuesta (**Response**) usando `@ZenProperty()`:
+
+```typescript
+// dto/user.dto.ts
+import { ZenProperty, ZenPropertyOptional } from 'nest-swagger-zen';
+
+export class CreateUserDto {
+  @ZenProperty({ example: 'juan@cliente.com', description: 'Correo electrónico' })
+  email: string;
+
+  @ZenProperty({ example: 'Juan Pérez' })
+  name: string;
+
+  @ZenPropertyOptional({ description: 'Edad del usuario', example: 28 })
+  age?: number;
+}
+
+export class UserResponseDto {
+  @ZenProperty({ example: 'User registered successfully' })
+  message: string;
+}
+```
+
+### 2. Extrae la Configuración a un archivo externo (Patrón Zen)
+La idea de esta librería es que tu controlador quede **100% libre de configuraciones**. Crea un archivo de definiciones (por ejemplo `swagger/user.swagger.ts`) donde guardarás toda la metadata, generando decoradores pre-configurados:
+
+```typescript
+// swagger/user.swagger.ts
+import { ZenSwagger } from 'nest-swagger-zen';
+import { CreateUserDto, UserResponseDto } from '../dto/user.dto';
+
+// Creas una constante que ya contiene el decorador listo
+export const CreateUserDocs = () => ZenSwagger({
+  summary: 'Create User',
+  description: 'Endpoint to create a new user in the system.',
+  status: 201, 
+  body: CreateUserDto, 
+  response: UserResponseDto 
+});
+```
+
+### 3. Aplica tus nuevos decoradores al Controlador
+Ahora, importa este decorador en tu controller. Fíjate cómo la lógica de tu endpoint queda absolutamente inmaculada:
+
+```typescript
+// user.controller.ts
+import { Controller, Post, Body } from '@nestjs/common';
+import { CreateUserDocs } from './swagger/user.swagger'; 
+import { CreateUserDto } from './dto/user.dto';
+
+@Controller('users')
+export class UserController {
+
+  @Post()
+  @CreateUserDocs() 
+  create(@Body() payload: CreateUserDto) {
+    return { message: "User registered successfully" };
+  }
+}
+```
+
+## Configuración ⚙️
+
+La interfaz `ZenSwaggerConfig` que puedes enviarle a `@ZenSwagger()` soporta abarcar toda la casuística de tu API de manera sencilla:
+
+- `summary` *(string, requerido)*: Título breve del endpoint.
+- `description` *(string, opcional)*: Descripción extendida.
+- `deprecated` *(boolean, opcional)*: Si se envía `true`, el endpoint aparecerá tachado en Swagger indicando que obsoleto.
+- `status` *(number, opcional)*: Código HTTP retornado al tener éxito (Default `200`).
+- `body` *(Type, opcional)*: Clase DTO para construir el modelo Swagger JSON del `body`.
+- `response` *(Type, opcional)*: Clase DTO para construir el modelo Swagger JSON de la respuesta.
+- `example` *(any, opcional)*: Valor puro a renderizar como respuesta de ejemplo (para respuestas primitivas).
+- `isPaginated` *(boolean, opcional)*: Si se envía `true`, agrega automáticamente los parámetros `page` y `limit`.
+- `isBearerAuth` *(boolean, opcional)*: Si se envía `true`, añade el requerimiento del token JWT (`@ApiBearerAuth`).
+- `params` *(array, opcional)*: Arreglo de objetos para documentar variables en la URL. Ej: `[{ name: 'id', description: 'ID de usuario' }]`.
+- `queries` *(array, opcional)*: Arreglo para mapear QueryStrings libres. Ej: `[{ name: 'search', required: false }]`.
+- `consumes` *(array de strings, opt)*: Útil para subida de archivos. Ej: `['multipart/form-data']`.
+- `exclude` *(boolean, opcional)*: Oculta el endpoint del UI de Swagger.

package/dist/decorators/property.decorator.d.ts

@@ -0,0 +1,3 @@
+import { ApiPropertyOptions } from '@nestjs/swagger';
+export declare function ZenProperty(options?: ApiPropertyOptions): PropertyDecorator;
+export declare function ZenPropertyOptional(options?: ApiPropertyOptions): PropertyDecorator;

package/dist/decorators/property.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZenProperty = ZenProperty;
+exports.ZenPropertyOptional = ZenPropertyOptional;
+const swagger_1 = require("@nestjs/swagger");
+function ZenProperty(options) {
+    return (0, swagger_1.ApiProperty)(options);
+}
+function ZenPropertyOptional(options) {
+    return (0, swagger_1.ApiPropertyOptional)(options);
+}
+//# sourceMappingURL=property.decorator.js.map

package/dist/decorators/property.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property.decorator.js","sourceRoot":"","sources":["../../src/decorators/property.decorator.ts"],"names":[],"mappings":";;AAOA,kCAEC;AAMD,kDAEC;AAjBD,6CAAuF;AAOvF,SAAgB,WAAW,CAAC,OAA4B;IACtD,OAAO,IAAA,qBAAW,EAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAMD,SAAgB,mBAAmB,CAAC,OAA4B;IAC9D,OAAO,IAAA,6BAAmB,EAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/decorators/swagger.decorator.d.ts

@@ -0,0 +1,19 @@
+import { Type } from '@nestjs/common';
+import { ApiParamOptions } from '@nestjs/swagger/dist/decorators/api-param.decorator';
+import { ApiQueryOptions } from '@nestjs/swagger/dist/decorators/api-query.decorator';
+export interface ZenSwaggerConfig {
+    summary: string;
+    description?: string;
+    deprecated?: boolean;
+    status?: number;
+    body?: Type<any>;
+    response?: Type<any>;
+    example?: any;
+    isPaginated?: boolean;
+    isBearerAuth?: boolean;
+    params?: ApiParamOptions[];
+    queries?: ApiQueryOptions[];
+    consumes?: string[];
+    exclude?: boolean;
+}
+export declare function ZenSwagger(config: ZenSwaggerConfig): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/dist/decorators/swagger.decorator.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZenSwagger = ZenSwagger;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+function ZenSwagger(config) {
+    const decorators = [];
+    if (config.exclude) {
+        decorators.push((0, swagger_1.ApiExcludeEndpoint)());
+    }
+    decorators.push((0, swagger_1.ApiOperation)({
+        summary: config.summary,
+        description: config.description,
+        deprecated: config.deprecated,
+    }));
+    if (config.isBearerAuth) {
+        decorators.push((0, swagger_1.ApiBearerAuth)());
+    }
+    if (config.consumes && config.consumes.length > 0) {
+        decorators.push((0, swagger_1.ApiConsumes)(...config.consumes));
+    }
+    if (config.response) {
+        decorators.push((0, swagger_1.ApiResponse)({
+            status: config.status || 200,
+            description: config.summary,
+            type: config.response,
+        }));
+    }
+    else if (config.example) {
+        decorators.push((0, swagger_1.ApiResponse)({
+            status: config.status || 200,
+            description: config.summary,
+            content: {
+                'application/json': {
+                    example: config.example,
+                },
+            },
+        }));
+    }
+    else {
+        decorators.push((0, swagger_1.ApiResponse)({
+            status: config.status || 200,
+            description: config.summary,
+        }));
+    }
+    if (config.body) {
+        decorators.push((0, swagger_1.ApiBody)({ type: config.body }));
+    }
+    if (config.isPaginated) {
+        decorators.push((0, swagger_1.ApiQuery)({ name: 'page', required: false, type: Number, example: 1 }), (0, swagger_1.ApiQuery)({ name: 'limit', required: false, type: Number, example: 10 }));
+    }
+    if (config.params && config.params.length > 0) {
+        config.params.forEach((param) => decorators.push((0, swagger_1.ApiParam)(param)));
+    }
+    if (config.queries && config.queries.length > 0) {
+        config.queries.forEach((query) => decorators.push((0, swagger_1.ApiQuery)(query)));
+    }
+    return (0, common_1.applyDecorators)(...decorators);
+}
+//# sourceMappingURL=swagger.decorator.js.map

package/dist/decorators/swagger.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.decorator.js","sourceRoot":"","sources":["../../src/decorators/swagger.decorator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './decorators/swagger.decorator';
+export * from './decorators/property.decorator';

package/dist/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("./decorators/swagger.decorator"), exports);
+__exportStar(require("./decorators/property.decorator"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA+C;AAC/C,kEAAgD"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@l337quez/nest-swagger-zen",
+  "version": "1.0.0",
+  "description": "A stylish, generalized library to prevent Swagger from cluttering NestJS controllers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "nestjs",
+    "swagger",
+    "decorators",
+    "zen"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/swagger": "^7.0.0",
+    "@types/node": "^20.0.0",
+    "reflect-metadata": "^0.1.0",
+    "rxjs": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "@nestjs/swagger": "^6.0.0 || ^7.0.0"
+  }
+}