@shadow-library/fastify 1.5.1 → 1.6.0

package/README.md

@@ -952,6 +952,62 @@ class CreateProductDto {
 }
 ```
 
+## API Documentation Metadata
+
+The `@ApiOperation` decorator allows you to add OpenAPI/Swagger metadata to your route handlers. This metadata is integrated into the Fastify route schema and can be consumed by documentation generators like Swagger UI.
+
+```typescript
+@ApiOperation({
+  summary: string;              // Short description of the operation
+  description?: string;         // Detailed description
+  tags?: string[];              // Operation tags for grouping
+  deprecated?: boolean;         // Mark if endpoint is deprecated
+  externalDocs?: {              // Link to external documentation
+    url: string;
+    description?: string;
+  };
+  security?: Record<string, []>; // Security requirements
+})
+```
+
+### Example Usage
+
+```typescript
+import { HttpController, Get, Post, Body, ApiOperation } from '@shadow-library/fastify';
+
+@HttpController('/api/users')
+export class UserController {
+  @Get()
+  @ApiOperation({
+    summary: 'List all users',
+    description: 'Retrieve a paginated list of all users in the system',
+    tags: ['users'],
+  })
+  async getUsers() {
+    return [];
+  }
+
+  @Post()
+  @ApiOperation({
+    summary: 'Create a new user',
+    tags: ['users'],
+    security: { bearerAuth: [] },
+  })
+  async createUser(@Body() userData: CreateUserDto) {
+    return { id: 1, ...userData };
+  }
+
+  @Get('/:id')
+  @ApiOperation({
+    summary: 'Get user by ID',
+    deprecated: false,
+  })
+  async getUserById() {
+    return { id: 1, name: 'John' };
+  }
+}
+```
+
 ## Data Transformation
 
 The `@Transform` decorator enables automatic data transformation at two key points in the request-response lifecycle:

package/cjs/decorators/api-operation.decorator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+export interface ApiOperationMetadata {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+    security?: Record<string, string[]>;
+    [key: string]: any;
+}
+/**
+ * Declaring the constants
+ */
+export declare function ApiOperation(options: ApiOperationMetadata): ClassDecorator & MethodDecorator;

package/cjs/decorators/api-operation.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiOperation = ApiOperation;
+/**
+ * Importing npm packages
+ */
+const app_1 = require("@shadow-library/app");
+/**
+ * Declaring the constants
+ */
+function ApiOperation(options) {
+    return (0, app_1.Route)({ operation: options });
+}

package/cjs/decorators/index.d.ts

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/cjs/decorators/index.js

@@ -14,6 +14,7 @@ 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("./api-operation.decorator.js"), exports);
 __exportStar(require("./http-controller.decorator.js"), exports);
 __exportStar(require("./http-input.decorator.js"), exports);
 __exportStar(require("./http-output.decorator.js"), exports);

package/cjs/interfaces/server-metadata.interface.d.ts

@@ -8,7 +8,7 @@ import { FastifyInstance, RouteShorthandOptions } from 'fastify';
  * Importing user defined packages
  */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
-import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
+import { ApiOperationMetadata, HttpMethod, RouteInputSchemas } from '../decorators/index.js';
 /**
  * Defining types
  */
@@ -20,6 +20,7 @@ declare module '@shadow-library/app' {
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema | SchemaClass>;
         };
+        operation?: ApiOperationMetadata;
         rawBody?: boolean;
         silentValidation?: boolean;
         status?: number;

package/cjs/module/fastify-router.js

@@ -157,6 +157,8 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
                         const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
                         const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
+                        if (metadata.operation || route.metadata.operation)
+                            route.metadata.operation = Object.assign({}, metadata.operation, route.metadata.operation);
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
                     }
@@ -311,7 +313,7 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
                 }
             }
             const responseSchemas = { ...defaultResponseSchemas };
-            routeOptions.schema = { response: responseSchemas };
+            routeOptions.schema = { ...metadata.operation, response: responseSchemas };
             routeOptions.attachValidation = metadata.silentValidation ?? false;
             const { body: bodySchema, params: paramsSchema, query: querySchema, response: responseSchema } = metadata.schemas ?? {};
             const isMaskEnabled = this.config.maskSensitiveData ?? true;

package/esm/decorators/api-operation.decorator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+export interface ApiOperationMetadata {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+    security?: Record<string, string[]>;
+    [key: string]: any;
+}
+/**
+ * Declaring the constants
+ */
+export declare function ApiOperation(options: ApiOperationMetadata): ClassDecorator & MethodDecorator;

package/esm/decorators/api-operation.decorator.js

@@ -0,0 +1,10 @@
+/**
+ * Importing npm packages
+ */
+import { Route } from '@shadow-library/app';
+/**
+ * Declaring the constants
+ */
+export function ApiOperation(options) {
+    return Route({ operation: options });
+}

package/esm/decorators/index.d.ts

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/esm/decorators/index.js

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/esm/interfaces/server-metadata.interface.d.ts

@@ -8,7 +8,7 @@ import { FastifyInstance, RouteShorthandOptions } from 'fastify';
  * Importing user defined packages
  */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
-import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
+import { ApiOperationMetadata, HttpMethod, RouteInputSchemas } from '../decorators/index.js';
 /**
  * Defining types
  */
@@ -20,6 +20,7 @@ declare module '@shadow-library/app' {
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema | SchemaClass>;
         };
+        operation?: ApiOperationMetadata;
         rawBody?: boolean;
         silentValidation?: boolean;
         status?: number;

package/esm/module/fastify-router.js

@@ -151,6 +151,8 @@ let FastifyRouter = class FastifyRouter extends Router {
                         const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
                         const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
+                        if (metadata.operation || route.metadata.operation)
+                            route.metadata.operation = Object.assign({}, metadata.operation, route.metadata.operation);
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
                     }
@@ -305,7 +307,7 @@ let FastifyRouter = class FastifyRouter extends Router {
                 }
             }
             const responseSchemas = { ...defaultResponseSchemas };
-            routeOptions.schema = { response: responseSchemas };
+            routeOptions.schema = { ...metadata.operation, response: responseSchemas };
             routeOptions.attachValidation = metadata.silentValidation ?? false;
             const { body: bodySchema, params: paramsSchema, query: querySchema, response: responseSchema } = metadata.schemas ?? {};
             const isMaskEnabled = this.config.maskSensitiveData ?? true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shadow-library/fastify",
   "type": "module",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "sideEffects": false,
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {