@riktajs/swagger 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# @riktajs/swagger
+
+[![npm version](https://img.shields.io/npm/v/@riktajs/swagger.svg)](https://www.npmjs.com/package/@riktajs/swagger)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automatic OpenAPI/Swagger documentation generation for the Rikta Framework.
+
+> **Note:** This package is completely agnostic from `@riktajs/core` - it only reads metadata and can be used with any Fastify application.
+
+## Features
+
+- 🚀 **Automatic route extraction** from `@Controller`, `@Get`, `@Post`, etc.
+- 🏷️ **Rich decorators** for API documentation (`@ApiTags`, `@ApiOperation`, `@ApiResponse`, etc.)
+- 📝 **Zod integration** for automatic request/response type documentation
+- 🎨 **Interactive Swagger UI** powered by `@fastify/swagger-ui`
+- 📋 **Full OpenAPI 3.0/3.1** specification support
+- 🔌 **Zero-config** with sensible defaults
+- 🏗️ **Completely agnostic** from `@riktajs/core` - can be used independently
+
+## Installation
+
+```bash
+npm install @riktajs/swagger
+```
+
+## Quick Start
+
+```typescript
+import { Rikta, Controller, Get, Body, Post } from '@riktajs/core';
+import { swaggerPlugin, ApiTags, ApiOperation, ApiResponse, ApiBody } from '@riktajs/swagger';
+import { z } from 'zod';
+
+// Define your schemas with Zod
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const CreateUserSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+});
+
+@ApiTags('Users')
+@Controller('/users')
+class UserController {
+  @Get('/')
+  @ApiOperation({ summary: 'List all users' })
+  @ApiResponse({ status: 200, description: 'Array of users', schema: z.array(UserSchema) })
+  async listUsers() {
+    return [];
+  }
+
+  @Post('/')
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiBody({ schema: CreateUserSchema })
+  @ApiResponse({ status: 201, description: 'User created', schema: UserSchema })
+  async createUser(@Body() data: z.infer<typeof CreateUserSchema>) {
+    return { id: 'uuid', ...data };
+  }
+}
+
+// Create and start the application
+const app = await Rikta.create({ port: 3000 });
+
+// Register swagger plugin
+await app.server.register(swaggerPlugin, {
+  title: 'My API',
+  version: '1.0.0',
+  description: 'My awesome API documentation',
+});
+
+await app.listen();
+
+// Swagger UI: http://localhost:3000/docs
+// OpenAPI JSON: http://localhost:3000/docs/json
+```
+
+## Configuration
+
+```typescript
+await app.server.register(swaggerPlugin, {
+  // Required
+  title: 'My API',
+  version: '1.0.0',
+  
+  // Optional
+  description: 'API description with **Markdown** support',
+  termsOfService: 'https://example.com/terms',
+  contact: {
+    name: 'API Support',
+    url: 'https://example.com/support',
+    email: 'support@example.com',
+  },
+  license: {
+    name: 'MIT',
+    url: 'https://opensource.org/licenses/MIT',
+  },
+  
+  // Server configuration
+  servers: [
+    { url: 'http://localhost:3000', description: 'Development' },
+    { url: 'https://api.example.com', description: 'Production' },
+  ],
+  
+  // Security schemes
+  securitySchemes: {
+    bearerAuth: {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+    },
+  },
+  
+  // Custom paths
+  uiPath: '/docs',       // Default: /docs
+  jsonPath: '/docs/json', // Default: /docs/json
+  
+  // OpenAPI version
+  openApiVersion: '3.0.3', // Default: 3.0.3
+});
+```
+
+## Decorators
+
+### Class Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@ApiTags(...tags)` | Group endpoints by tags |
+| `@ApiBearerAuth()` | Apply Bearer auth to all endpoints |
+| `@ApiSecurity(name, scopes?)` | Apply security requirement |
+
+### Method Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@ApiOperation(options)` | Describe the operation (summary, description) |
+| `@ApiResponse(options)` | Document a response (status, schema, description) |
+| `@ApiBody(options)` | Document request body |
+| `@ApiParam(options)` | Document path parameter |
+| `@ApiQuery(options)` | Document query parameter |
+| `@ApiHeader(options)` | Document header parameter |
+| `@ApiExcludeEndpoint()` | Exclude endpoint from documentation |
+
+### Property Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@ApiProperty(options)` | Document DTO property |
+
+## Zod Integration
+
+The package automatically converts Zod schemas to OpenAPI schemas:
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string().uuid().describe('Unique user identifier'),
+  name: z.string().min(2).max(100),
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150).optional(),
+  role: z.enum(['admin', 'user', 'guest']),
+  createdAt: z.date(),
+});
+
+// Use in decorators
+@ApiResponse({ status: 200, schema: UserSchema })
+```
+
+Supported Zod types:
+- Primitives: `string`, `number`, `boolean`, `bigint`
+- Complex: `object`, `array`, `tuple`, `record`
+- Modifiers: `optional`, `nullable`, `default`
+- Validators: `min`, `max`, `email`, `uuid`, `url`, etc.
+- Enums: `enum`, `nativeEnum`
+- Unions and intersections
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## Alternative APIs
+
+### registerSwagger Helper
+
+A simpler API for registering the plugin:
+
+```typescript
+import { registerSwagger } from '@riktajs/swagger';
+
+await registerSwagger(app, {
+  info: {
+    title: 'My API',
+    version: '1.0.0',
+  },
+});
+```
+
+### createSwaggerConfig
+
+For more control or integration with existing Fastify apps:
+
+```typescript
+import fastify from 'fastify';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUI from '@fastify/swagger-ui';
+import { createSwaggerConfig } from '@riktajs/swagger';
+
+const app = fastify();
+const { swaggerOptions, swaggerUIOptions, specification } = createSwaggerConfig({
+  info: { title: 'My API', version: '1.0.0' },
+  controllers: [UserController, ProductController],
+});
+
+await app.register(fastifySwagger, swaggerOptions);
+await app.register(fastifySwaggerUI, swaggerUIOptions);
+```
+
+### OpenApiGenerator Direct Usage
+
+Generate OpenAPI spec without Fastify:
+
+```typescript
+import { OpenApiGenerator } from '@riktajs/swagger';
+
+const generator = new OpenApiGenerator({
+  info: { title: 'My API', version: '1.0.0' },
+});
+
+generator.addController(UserController);
+generator.addController(ProductController);
+
+const spec = generator.generate();
+console.log(JSON.stringify(spec, null, 2));
+```
+
+## Related Packages
+
+- [@riktajs/core](https://www.npmjs.com/package/@riktajs/core) - Rikta Framework core
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Key for storing API tags on controller classes
+ * Used by @ApiTags() decorator
+ */
+export declare const API_TAGS_METADATA: unique symbol;
+/**
+ * Key for storing API operation metadata on route methods
+ * Used by @ApiOperation() decorator
+ */
+export declare const API_OPERATION_METADATA: unique symbol;
+/**
+ * Key for storing API response metadata on route methods
+ * Used by @ApiResponse() decorator
+ */
+export declare const API_RESPONSE_METADATA: unique symbol;
+/**
+ * Key for storing API property metadata on class properties
+ * Used by @ApiProperty() decorator
+ */
+export declare const API_PROPERTY_METADATA: unique symbol;
+/**
+ * Key for storing API body metadata on route methods
+ * Used by @ApiBody() decorator
+ */
+export declare const API_BODY_METADATA: unique symbol;
+/**
+ * Key for storing API parameter metadata on route methods
+ * Used by @ApiParam() decorator
+ */
+export declare const API_PARAM_METADATA: unique symbol;
+/**
+ * Key for storing API query metadata on route methods
+ * Used by @ApiQuery() decorator
+ */
+export declare const API_QUERY_METADATA: unique symbol;
+/**
+ * Key for storing API header metadata on route methods
+ * Used by @ApiHeader() decorator
+ */
+export declare const API_HEADER_METADATA: unique symbol;
+/**
+ * Key for storing API security metadata on route methods or controllers
+ * Used by @ApiSecurity() and @ApiBearerAuth() decorators
+ */
+export declare const API_SECURITY_METADATA: unique symbol;
+/**
+ * Key for storing API exclude metadata on route methods
+ * Used by @ApiExcludeEndpoint() decorator
+ */
+export declare const API_EXCLUDE_METADATA: unique symbol;
+/**
+ * Key for storing API deprecated metadata on route methods
+ * Used when operation is marked as deprecated
+ */
+export declare const API_DEPRECATED_METADATA: unique symbol;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,eAAsC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,eAA2C,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAA0C,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAA0C,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,iBAAiB,eAAsC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,eAAuC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,eAAuC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAA0C,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,eAAyC,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,eAA4C,CAAC"}

package/dist/constants.js

@@ -0,0 +1,61 @@
+// ============================================================================
+// Swagger Package - Metadata Keys
+// ============================================================================
+// Using Symbol.for() to ensure symbols are shared across packages
+// and different import contexts (bundlers, tests, etc.)
+/**
+ * Key for storing API tags on controller classes
+ * Used by @ApiTags() decorator
+ */
+export const API_TAGS_METADATA = Symbol.for('rikta:swagger:apiTags');
+/**
+ * Key for storing API operation metadata on route methods
+ * Used by @ApiOperation() decorator
+ */
+export const API_OPERATION_METADATA = Symbol.for('rikta:swagger:apiOperation');
+/**
+ * Key for storing API response metadata on route methods
+ * Used by @ApiResponse() decorator
+ */
+export const API_RESPONSE_METADATA = Symbol.for('rikta:swagger:apiResponse');
+/**
+ * Key for storing API property metadata on class properties
+ * Used by @ApiProperty() decorator
+ */
+export const API_PROPERTY_METADATA = Symbol.for('rikta:swagger:apiProperty');
+/**
+ * Key for storing API body metadata on route methods
+ * Used by @ApiBody() decorator
+ */
+export const API_BODY_METADATA = Symbol.for('rikta:swagger:apiBody');
+/**
+ * Key for storing API parameter metadata on route methods
+ * Used by @ApiParam() decorator
+ */
+export const API_PARAM_METADATA = Symbol.for('rikta:swagger:apiParam');
+/**
+ * Key for storing API query metadata on route methods
+ * Used by @ApiQuery() decorator
+ */
+export const API_QUERY_METADATA = Symbol.for('rikta:swagger:apiQuery');
+/**
+ * Key for storing API header metadata on route methods
+ * Used by @ApiHeader() decorator
+ */
+export const API_HEADER_METADATA = Symbol.for('rikta:swagger:apiHeader');
+/**
+ * Key for storing API security metadata on route methods or controllers
+ * Used by @ApiSecurity() and @ApiBearerAuth() decorators
+ */
+export const API_SECURITY_METADATA = Symbol.for('rikta:swagger:apiSecurity');
+/**
+ * Key for storing API exclude metadata on route methods
+ * Used by @ApiExcludeEndpoint() decorator
+ */
+export const API_EXCLUDE_METADATA = Symbol.for('rikta:swagger:apiExclude');
+/**
+ * Key for storing API deprecated metadata on route methods
+ * Used when operation is marked as deprecated
+ */
+export const API_DEPRECATED_METADATA = Symbol.for('rikta:swagger:apiDeprecated');
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAC/E,kEAAkE;AAClE,wDAAwD;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAE3E;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC"}

package/dist/decorators/api-body.decorator.d.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata';
+import type { ApiBodyOptions } from '../types.js';
+/**
+ * @ApiBody() decorator
+ *
+ * Documents the request body for an API operation.
+ * Supports both Zod schemas and OpenAPI schema objects.
+ *
+ * @param options - Body options including schema, description, and examples
+ *
+ * @example
+ * ```typescript
+ * const CreateUserSchema = z.object({
+ *   name: z.string().min(2),
+ *   email: z.string().email(),
+ * });
+ *
+ * @Post('/')
+ * @ApiBody({
+ *   description: 'User creation data',
+ *   schema: CreateUserSchema,
+ *   required: true,
+ * })
+ * createUser(@Body() data: z.infer<typeof CreateUserSchema>) { }
+ * ```
+ */
+export declare function ApiBody(options: ApiBodyOptions): MethodDecorator;
+/**
+ * Get body metadata from a method
+ * @internal
+ */
+export declare function getApiBody(target: Function, propertyKey: string | symbol): ApiBodyOptions | undefined;
+//# sourceMappingURL=api-body.decorator.d.ts.map

package/dist/decorators/api-body.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-body.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/api-body.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAchE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,cAAc,GAAG,SAAS,CAE5B"}

package/dist/decorators/api-body.decorator.js

@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+import { API_BODY_METADATA } from '../constants.js';
+/**
+ * @ApiBody() decorator
+ *
+ * Documents the request body for an API operation.
+ * Supports both Zod schemas and OpenAPI schema objects.
+ *
+ * @param options - Body options including schema, description, and examples
+ *
+ * @example
+ * ```typescript
+ * const CreateUserSchema = z.object({
+ *   name: z.string().min(2),
+ *   email: z.string().email(),
+ * });
+ *
+ * @Post('/')
+ * @ApiBody({
+ *   description: 'User creation data',
+ *   schema: CreateUserSchema,
+ *   required: true,
+ * })
+ * createUser(@Body() data: z.infer<typeof CreateUserSchema>) { }
+ * ```
+ */
+export function ApiBody(options) {
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(API_BODY_METADATA, { ...options, required: options.required ?? true }, target, propertyKey);
+        return descriptor;
+    };
+}
+/**
+ * Get body metadata from a method
+ * @internal
+ */
+export function getApiBody(target, propertyKey) {
+    return Reflect.getMetadata(API_BODY_METADATA, target.prototype, propertyKey);
+}
+//# sourceMappingURL=api-body.decorator.js.map

package/dist/decorators/api-body.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-body.decorator.js","sourceRoot":"","sources":["../../src/decorators/api-body.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,OAAO,CAAC,OAAuB;IAC7C,OAAO,CACL,MAAc,EACd,WAA4B,EAC5B,UAA8B,EACV,EAAE;QACtB,OAAO,CAAC,cAAc,CACpB,iBAAiB,EACjB,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,EAClD,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,MAAgB,EAChB,WAA4B;IAE5B,OAAO,OAAO,CAAC,WAAW,CAAC,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAC/E,CAAC"}

package/dist/decorators/api-exclude.decorator.d.ts

@@ -0,0 +1,71 @@
+import 'reflect-metadata';
+/**
+ * @ApiExcludeEndpoint() decorator
+ *
+ * Excludes an endpoint from the Swagger documentation.
+ * The route will still work but won't appear in the docs.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/')
+ *   listUsers() { } // Documented
+ *
+ *   @Get('/internal')
+ *   @ApiExcludeEndpoint()
+ *   internalEndpoint() { } // Not documented
+ * }
+ * ```
+ */
+export declare function ApiExcludeEndpoint(): MethodDecorator;
+/**
+ * @ApiExcludeController() decorator
+ *
+ * Excludes an entire controller from the Swagger documentation.
+ * All routes in the controller will still work but won't appear in the docs.
+ *
+ * @example
+ * ```typescript
+ * @ApiExcludeController()
+ * @Controller('/internal')
+ * class InternalController {
+ *   @Get('/health')
+ *   health() { } // Not documented
+ * }
+ * ```
+ */
+export declare function ApiExcludeController(): ClassDecorator;
+/**
+ * Check if an endpoint is excluded from documentation
+ * @internal
+ */
+export declare function isApiExcluded(target: Function, propertyKey?: string | symbol): boolean;
+/**
+ * @ApiDeprecated() decorator
+ *
+ * Marks an endpoint as deprecated in the documentation.
+ * The endpoint will be styled differently in Swagger UI.
+ *
+ * @param message - Optional deprecation message
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/v1')
+ *   @ApiDeprecated('Use /v2 instead')
+ *   legacyEndpoint() { }
+ * }
+ * ```
+ */
+export declare function ApiDeprecated(message?: string): MethodDecorator;
+/**
+ * Check if an endpoint is deprecated
+ * @internal
+ */
+export declare function getApiDeprecated(target: Function, propertyKey: string | symbol): {
+    deprecated: boolean;
+    message?: string;
+} | undefined;
+//# sourceMappingURL=api-exclude.decorator.d.ts.map

package/dist/decorators/api-exclude.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exclude.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/api-exclude.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAcpD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAIrD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAUtF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAc/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAEvD"}

package/dist/decorators/api-exclude.decorator.js

@@ -0,0 +1,95 @@
+import 'reflect-metadata';
+import { API_EXCLUDE_METADATA, API_DEPRECATED_METADATA } from '../constants.js';
+/**
+ * @ApiExcludeEndpoint() decorator
+ *
+ * Excludes an endpoint from the Swagger documentation.
+ * The route will still work but won't appear in the docs.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/')
+ *   listUsers() { } // Documented
+ *
+ *   @Get('/internal')
+ *   @ApiExcludeEndpoint()
+ *   internalEndpoint() { } // Not documented
+ * }
+ * ```
+ */
+export function ApiExcludeEndpoint() {
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(API_EXCLUDE_METADATA, true, target, propertyKey);
+        return descriptor;
+    };
+}
+/**
+ * @ApiExcludeController() decorator
+ *
+ * Excludes an entire controller from the Swagger documentation.
+ * All routes in the controller will still work but won't appear in the docs.
+ *
+ * @example
+ * ```typescript
+ * @ApiExcludeController()
+ * @Controller('/internal')
+ * class InternalController {
+ *   @Get('/health')
+ *   health() { } // Not documented
+ * }
+ * ```
+ */
+export function ApiExcludeController() {
+    return (target) => {
+        Reflect.defineMetadata(API_EXCLUDE_METADATA, true, target);
+    };
+}
+/**
+ * Check if an endpoint is excluded from documentation
+ * @internal
+ */
+export function isApiExcluded(target, propertyKey) {
+    // Check class-level exclusion
+    if (Reflect.getMetadata(API_EXCLUDE_METADATA, target) === true) {
+        return true;
+    }
+    // Check method-level exclusion
+    if (propertyKey !== undefined) {
+        return Reflect.getMetadata(API_EXCLUDE_METADATA, target.prototype, propertyKey) === true;
+    }
+    return false;
+}
+/**
+ * @ApiDeprecated() decorator
+ *
+ * Marks an endpoint as deprecated in the documentation.
+ * The endpoint will be styled differently in Swagger UI.
+ *
+ * @param message - Optional deprecation message
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/v1')
+ *   @ApiDeprecated('Use /v2 instead')
+ *   legacyEndpoint() { }
+ * }
+ * ```
+ */
+export function ApiDeprecated(message) {
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(API_DEPRECATED_METADATA, { deprecated: true, message }, target, propertyKey);
+        return descriptor;
+    };
+}
+/**
+ * Check if an endpoint is deprecated
+ * @internal
+ */
+export function getApiDeprecated(target, propertyKey) {
+    return Reflect.getMetadata(API_DEPRECATED_METADATA, target.prototype, propertyKey);
+}
+//# sourceMappingURL=api-exclude.decorator.js.map

package/dist/decorators/api-exclude.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exclude.decorator.js","sourceRoot":"","sources":["../../src/decorators/api-exclude.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CACL,MAAc,EACd,WAA4B,EAC5B,UAA8B,EACV,EAAE;QACtB,OAAO,CAAC,cAAc,CACpB,oBAAoB,EACpB,IAAI,EACJ,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,MAAgB,EAAQ,EAAE;QAChC,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAgB,EAAE,WAA6B;IAC3E,8BAA8B;IAC9B,IAAI,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,+BAA+B;IAC/B,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,CACL,MAAc,EACd,WAA4B,EAC5B,UAA8B,EACV,EAAE;QACtB,OAAO,CAAC,cAAc,CACpB,uBAAuB,EACvB,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,EAC7B,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAgB,EAChB,WAA4B;IAE5B,OAAO,OAAO,CAAC,WAAW,CAAC,uBAAuB,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AACrF,CAAC"}

package/dist/decorators/api-header.decorator.d.ts

@@ -0,0 +1,25 @@
+import 'reflect-metadata';
+import type { ApiHeaderOptions } from '../types.js';
+/**
+ * @ApiHeader() decorator
+ *
+ * Documents a header parameter for an API operation.
+ * Multiple @ApiHeader decorators can be applied for routes with multiple headers.
+ *
+ * @param options - Header options including name, description, and required flag
+ *
+ * @example
+ * ```typescript
+ * @Get('/')
+ * @ApiHeader({ name: 'X-Request-ID', description: 'Unique request identifier', required: true })
+ * @ApiHeader({ name: 'X-Correlation-ID', description: 'Correlation ID for tracing' })
+ * listUsers() { }
+ * ```
+ */
+export declare function ApiHeader(options: ApiHeaderOptions): MethodDecorator;
+/**
+ * Get all header parameter metadata from a method
+ * @internal
+ */
+export declare function getApiHeaders(target: Function, propertyKey: string | symbol): ApiHeaderOptions[];
+//# sourceMappingURL=api-header.decorator.d.ts.map

package/dist/decorators/api-header.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-header.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/api-header.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAiBpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,gBAAgB,EAAE,CAEpB"}