@globalart/nestjs-swagger 1.2.3

package/README.md

@@ -0,0 +1,204 @@
+# @globalart/nestjs-swagger
+
+A simple documentation builder for NestJS Swagger module that simplifies creating OpenAPI documentation for your REST APIs.
+
+## Installation
+
+```bash
+npm install @globalart/nestjs-swagger
+```
+
+or
+
+```bash
+yarn add @globalart/nestjs-swagger
+```
+
+## Description
+
+This package provides a convenient `SwaggerDocumentation` decorator for automatic Swagger documentation generation in NestJS applications. It significantly simplifies the process of adding documentation to your endpoints by providing a unified interface for describing operations and possible errors.
+
+## Key Features
+
+- 📝 Simple decorator for endpoint documentation
+- 🔧 Pre-configured descriptions for standard HTTP errors
+- 📊 Support for paginated responses
+- 🎯 Support for arrays in responses
+- 📋 Automatic schema generation for DTOs
+- 🛡️ Full TypeScript typing
+
+## Quick Start
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { SwaggerDocumentation, ERROR_DESCRIPTIONS } from '@globalart/nestjs-swagger';
+
+@Controller('users')
+export class UsersController {
+  @Get()
+  @SwaggerDocumentation({
+    endpointDescription: 'Get list of all users',
+    endpointSummary: 'List users',
+    error400Description: ERROR_DESCRIPTIONS.BAD_REQUEST,
+    error401Description: ERROR_DESCRIPTIONS.UNAUTHORIZED,
+    error500Description: ERROR_DESCRIPTIONS.INTERNAL_SERVER_ERROR
+  })
+  async getAllUsers() {
+    return [];
+  }
+}
+```
+
+## API Reference
+
+### SwaggerDocumentation
+
+Decorator for automatic Swagger documentation generation.
+
+#### Parameters
+
+| Parameter             | Type       | Description                          |
+| --------------------- | ---------- | ------------------------------------ |
+| `endpointDescription` | `string`   | Detailed endpoint description        |
+| `endpointSummary`     | `string`   | Brief endpoint description           |
+| `responseDto`         | `Function` | DTO class for response               |
+| `isArray`             | `boolean`  | Indicates that response is an array  |
+| `isPaginated`         | `boolean`  | Indicates that response is paginated |
+| `error400Description` | `string`   | 400 error description                |
+| `error401Description` | `string`   | 401 error description                |
+| `error403Description` | `string`   | 403 error description                |
+| `error404Description` | `string`   | 404 error description                |
+| `error409Description` | `string`   | 409 error description                |
+| `error422Description` | `string`   | 422 error description                |
+| `error429Description` | `string`   | 429 error description                |
+| `error500Description` | `string`   | 500 error description                |
+| `error503Description` | `string`   | 503 error description                |
+
+### ERROR_DESCRIPTIONS
+
+Object with pre-configured error descriptions:
+
+```typescript
+export const ERROR_DESCRIPTIONS = {
+  BAD_REQUEST: "Invalid request data or parameters",
+  UNAUTHORIZED: "Authentication required", 
+  FORBIDDEN: "Access denied",
+  NOT_FOUND: "Resource not found",
+  CONFLICT: "Resource already exists or conflict detected",
+  UNPROCESSABLE_ENTITY: "Validation error",
+  RATE_LIMIT_EXCEEDED: "Rate limit exceeded. Too many requests",
+  INTERNAL_SERVER_ERROR: "Internal server error",
+  SERVICE_UNAVAILABLE: "Service temporarily unavailable"
+};
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { SwaggerDocumentation, ERROR_DESCRIPTIONS } from '@globalart/nestjs-swagger';
+
+@Controller()
+export class AppController {
+  @Get('hello')
+  @SwaggerDocumentation({
+    endpointDescription: 'Simple greeting endpoint',
+    endpointSummary: 'Greeting',
+    error400Description: ERROR_DESCRIPTIONS.BAD_REQUEST,
+    error401Description: ERROR_DESCRIPTIONS.UNAUTHORIZED,
+    error403Description: ERROR_DESCRIPTIONS.FORBIDDEN,
+    error404Description: ERROR_DESCRIPTIONS.NOT_FOUND,
+    error429Description: ERROR_DESCRIPTIONS.RATE_LIMIT_EXCEEDED,
+    error500Description: ERROR_DESCRIPTIONS.INTERNAL_SERVER_ERROR
+  })
+  async hello() {
+    return 'Hello World';
+  }
+}
+```
+
+### Using with DTO
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class UserDto {
+  @ApiProperty()
+  id: number;
+
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  email: string;
+}
+
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  @SwaggerDocumentation({
+    endpointDescription: 'Get user by ID',
+    endpointSummary: 'Get user',
+    responseDto: UserDto,
+    error404Description: ERROR_DESCRIPTIONS.NOT_FOUND,
+    error500Description: ERROR_DESCRIPTIONS.INTERNAL_SERVER_ERROR
+  })
+  async getUserById(@Param('id') id: number) {
+    // user retrieval logic
+  }
+}
+```
+
+### Working with Arrays
+
+```typescript
+@Controller('users')
+export class UsersController {
+  @Get()
+  @SwaggerDocumentation({
+    endpointDescription: 'Get list of all users',
+    endpointSummary: 'List users',
+    responseDto: UserDto,
+    isArray: true,
+    error500Description: ERROR_DESCRIPTIONS.INTERNAL_SERVER_ERROR
+  })
+  async getAllUsers() {
+    // user list retrieval logic
+  }
+}
+```
+
+### Paginated Responses
+
+```typescript
+@Controller('users')
+export class UsersController {
+  @Get()
+  @SwaggerDocumentation({
+    endpointDescription: 'Get paginated list of users',
+    endpointSummary: 'Paginated user list',
+    responseDto: UserDto,
+    isPaginated: true,
+    error400Description: ERROR_DESCRIPTIONS.BAD_REQUEST,
+    error500Description: ERROR_DESCRIPTIONS.INTERNAL_SERVER_ERROR
+  })
+  async getPaginatedUsers(@Query() query: PaginationDto) {
+    // pagination logic
+  }
+}
+```
+
+## Paginated Response Structure
+
+When using `isPaginated: true`, the response is automatically wrapped in the structure:
+
+```typescript
+{
+  data: T[],        // array of objects of the specified DTO
+  totalCount: number,  // total number of records
+  offset: number,      // offset
+  limit: number        // limit of records per page
+}
+```

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const API_RESPONSE_DESCRIPTION = "If the server is available, it always responds with code 200 or 201. Error code 400 and higher will replace the ok field: it equals false and the error text in the error field. If the input data does not pass validation, the error field contains an object with invalid fields and error text";
+export declare const ERROR_DESCRIPTIONS: {
+    BAD_REQUEST: string;
+    UNAUTHORIZED: string;
+    FORBIDDEN: string;
+    NOT_FOUND: string;
+    CONFLICT: string;
+    UNPROCESSABLE_ENTITY: string;
+    RATE_LIMIT_EXCEEDED: string;
+    INTERNAL_SERVER_ERROR: string;
+    SERVICE_UNAVAILABLE: string;
+};

package/dist/constants.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_DESCRIPTIONS = exports.API_RESPONSE_DESCRIPTION = void 0;
+exports.API_RESPONSE_DESCRIPTION = "If the server is available, it always responds with code 200 or 201. Error code 400 and higher will replace the ok field: it equals false and the error text in the error field. If the input data does not pass validation, the error field contains an object with invalid fields and error text";
+exports.ERROR_DESCRIPTIONS = {
+    BAD_REQUEST: "Invalid request data or parameters",
+    UNAUTHORIZED: "Authentication required",
+    FORBIDDEN: "Access denied",
+    NOT_FOUND: "Resource not found",
+    CONFLICT: "Resource already exists or conflict detected",
+    UNPROCESSABLE_ENTITY: "Validation error",
+    RATE_LIMIT_EXCEEDED: "Rate limit exceeded. Too many requests",
+    INTERNAL_SERVER_ERROR: "Internal server error",
+    SERVICE_UNAVAILABLE: "Service temporarily unavailable",
+};

package/dist/decorators/index.d.ts

@@ -0,0 +1,2 @@
+import { SwaggerDocumentationOptions } from "../interfaces";
+export declare const SwaggerDocumentation: (data: SwaggerDocumentationOptions) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/dist/decorators/index.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerDocumentation = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const constants_1 = require("../constants");
+const dtos_1 = require("../dtos");
+// SwaggerDocumentation is a decorator function to generate Swagger documentation for endpoints based on the provided options.
+const SwaggerDocumentation = (data) => {
+    const decorators = [
+        (0, swagger_1.ApiOperation)({
+            description: data.endpointDescription,
+            summary: data.endpointSummary,
+        }),
+    ];
+    if (data.error400Description) {
+        decorators.push((0, swagger_1.ApiBadRequestResponse)({
+            description: data.error400Description,
+        }));
+    }
+    if (data.error401Description) {
+        decorators.push((0, swagger_1.ApiUnauthorizedResponse)({
+            description: data.error401Description,
+        }));
+    }
+    if (data.error403Description) {
+        decorators.push((0, swagger_1.ApiForbiddenResponse)({
+            description: data.error403Description,
+        }));
+    }
+    if (data.error404Description) {
+        decorators.push((0, swagger_1.ApiNotFoundResponse)({
+            description: data.error404Description,
+        }));
+    }
+    if (data.error409Description) {
+        decorators.push((0, swagger_1.ApiConflictResponse)({
+            description: data.error409Description,
+        }));
+    }
+    if (data.error422Description) {
+        decorators.push((0, swagger_1.ApiUnprocessableEntityResponse)({
+            description: data.error422Description,
+        }));
+    }
+    if (data.error429Description) {
+        decorators.push((0, swagger_1.ApiTooManyRequestsResponse)({
+            description: data.error429Description,
+        }));
+    }
+    if (data.error500Description) {
+        decorators.push((0, swagger_1.ApiInternalServerErrorResponse)({
+            description: data.error500Description,
+        }));
+    }
+    if (data.error503Description) {
+        decorators.push((0, swagger_1.ApiServiceUnavailableResponse)({
+            description: data.error503Description,
+        }));
+    }
+    if (data.isPaginated && data.responseDto) {
+        decorators.push((0, swagger_1.ApiOkResponse)({
+            schema: {
+                allOf: [
+                    { $ref: (0, swagger_1.getSchemaPath)(dtos_1.PaginatedResponseDto) },
+                    {
+                        properties: {
+                            data: {
+                                type: "array",
+                                items: {
+                                    $ref: (0, swagger_1.getSchemaPath)(data.responseDto),
+                                },
+                            },
+                        },
+                    },
+                ],
+            },
+            description: constants_1.API_RESPONSE_DESCRIPTION,
+        }), (0, swagger_1.ApiExtraModels)(data.responseDto, dtos_1.PaginatedResponseDto));
+    }
+    else if (data.responseDto) {
+        decorators.push((0, swagger_1.ApiOkResponse)({
+            schema: data.isArray
+                ? {
+                    type: "array",
+                    items: { $ref: (0, swagger_1.getSchemaPath)(data.responseDto) },
+                }
+                : { $ref: (0, swagger_1.getSchemaPath)(data.responseDto) },
+            description: constants_1.API_RESPONSE_DESCRIPTION,
+        }), (0, swagger_1.ApiExtraModels)(data.responseDto));
+    }
+    else {
+        decorators.push((0, swagger_1.ApiOkResponse)({
+            description: constants_1.API_RESPONSE_DESCRIPTION,
+        }));
+    }
+    return (0, common_1.applyDecorators)(...decorators);
+};
+exports.SwaggerDocumentation = SwaggerDocumentation;

package/dist/dtos/index.d.ts

@@ -0,0 +1,6 @@
+export declare class PaginatedResponseDto<T> {
+    data: T[];
+    totalCount: number;
+    offset: number;
+    limit: number;
+}

package/dist/dtos/index.js

@@ -0,0 +1,32 @@
+"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.PaginatedResponseDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+class PaginatedResponseDto {
+    data;
+    totalCount;
+    offset;
+    limit;
+}
+exports.PaginatedResponseDto = PaginatedResponseDto;
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    __metadata("design:type", Number)
+], PaginatedResponseDto.prototype, "totalCount", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    __metadata("design:type", Number)
+], PaginatedResponseDto.prototype, "offset", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    __metadata("design:type", Number)
+], PaginatedResponseDto.prototype, "limit", void 0);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./constants";
+export * from "./decorators";
+export * from "./interfaces";

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("./constants"), exports);
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./interfaces"), exports);

package/dist/interfaces/index.d.ts

@@ -0,0 +1,18 @@
+export interface SwaggerDocumentationErrorStatus {
+    error400Description?: string;
+    error401Description?: string;
+    error403Description?: string;
+    error404Description?: string;
+    error409Description?: string;
+    error422Description?: string;
+    error429Description?: string;
+    error500Description?: string;
+    error503Description?: string;
+}
+export interface SwaggerDocumentationOptions extends SwaggerDocumentationErrorStatus {
+    endpointDescription?: string;
+    endpointSummary?: string;
+    responseDto?: Function;
+    isArray?: boolean;
+    isPaginated?: boolean;
+}

package/dist/interfaces/index.js

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

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@globalart/nestjs-swagger",
+  "version": "1.2.3",
+  "description": "A simple documentation builder for NestJS Swagger Module",
+  "author": {
+    "name": "GlobalArt, Inc"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GlobalArtInc/nestjs-toolkit.git#main"
+  },
+  "keywords": [
+    "nestjs",
+    "swagger",
+    "documentation"
+  ],
+  "scripts": {
+    "format": "prettier --write \"**/*.ts\"",
+    "test": "jest --runInBand --passWithNoTests",
+    "test:cov": "jest --coverage --passWithNoTests",
+    "coveralls": "yarn run test:cov --coverageReporters=text-lcov | coveralls",
+    "build": "rm -rf ./dist && tsc",
+    "prepublishOnly": "npm run build",
+    "publish:dev": "npm publish --access public --tag dev",
+    "publish:npm": "release-it"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.1.0",
+    "@nestjs/core": "^11.1.0",
+    "@nestjs/swagger": "^11.2.0",
+    "@nestjs/testing": "^11.1.0",
+    "@nestjs/typeorm": "^11.0.0",
+    "mysql": "^2.17.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.7",
+    "coveralls": "^3.0.5",
+    "jest": "^30.0.2",
+    "prettier": "^3.5.3",
+    "reflect-metadata": "^0.2.2",
+    "release-it": "19.0.3",
+    "rxjs": "^7.8.1",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.0.0",
+    "typeorm": "0.3.25",
+    "typescript": "^5.8.3"
+  },
+  "jest": {
+    "coveragePathIgnorePatterns": [
+      "src/__tests__"
+    ],
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".spec.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "coverageDirectory": "../coverage"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}