@riktajs/swagger 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,57 +1,3 @@
-/**
- * @riktajs/swagger
- *
- * Automatic OpenAPI/Swagger documentation generation for Rikta Framework.
- *
- * This package provides decorators and utilities to automatically generate
- * OpenAPI 3.0/3.1 documentation from your Rikta controllers and routes.
- *
- * Features:
- * - Automatic route extraction from @Controller, @Get, @Post, etc.
- * - Decorators for enriching API documentation (@ApiTags, @ApiOperation, @ApiResponse, etc.)
- * - Zod schema integration for automatic request/response type documentation
- * - Interactive Swagger UI served via Fastify
- * - Full OpenAPI 3.0/3.1 specification support
- *
- * @example
- * ```typescript
- * import { Rikta, Controller, Get } from '@riktajs/core';
- * import { swaggerPlugin, ApiTags, ApiOperation, ApiResponse } from '@riktajs/swagger';
- * import { z } from 'zod';
- *
- * const UserSchema = z.object({
- *   id: z.string().uuid(),
- *   name: z.string(),
- *   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 [];
- *   }
- * }
- *
- * const app = await Rikta.create({ port: 3000 });
- *
- * // Register swagger plugin
- * app.server.register(swaggerPlugin, {
- *   title: 'My API',
- *   version: '1.0.0',
- *   description: 'My awesome API documentation',
- * });
- *
- * await app.listen();
- * // Swagger UI available at http://localhost:3000/docs
- * // OpenAPI JSON available at http://localhost:3000/docs/json
- * ```
- *
- * @packageDocumentation
- */
 export * from './constants.js';
 export { CONTROLLER_METADATA, ROUTES_METADATA, PARAM_METADATA, HTTP_CODE_METADATA, GUARDS_METADATA, ZOD_SCHEMA_METADATA, } from '@riktajs/core';
 export type * from './types.js';
@@ -59,4 +5,3 @@ export * from './decorators/index.js';
 export { OpenApiGenerator } from './openapi/generator.js';
 export { zodToOpenApi, toOpenApiSchema, isZodSchema } from './openapi/zod-to-openapi.js';
 export { swaggerPlugin, registerSwagger, createSwaggerConfig } from './plugin/swagger.plugin.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,68 +1,6 @@
-/**
- * @riktajs/swagger
- *
- * Automatic OpenAPI/Swagger documentation generation for Rikta Framework.
- *
- * This package provides decorators and utilities to automatically generate
- * OpenAPI 3.0/3.1 documentation from your Rikta controllers and routes.
- *
- * Features:
- * - Automatic route extraction from @Controller, @Get, @Post, etc.
- * - Decorators for enriching API documentation (@ApiTags, @ApiOperation, @ApiResponse, etc.)
- * - Zod schema integration for automatic request/response type documentation
- * - Interactive Swagger UI served via Fastify
- * - Full OpenAPI 3.0/3.1 specification support
- *
- * @example
- * ```typescript
- * import { Rikta, Controller, Get } from '@riktajs/core';
- * import { swaggerPlugin, ApiTags, ApiOperation, ApiResponse } from '@riktajs/swagger';
- * import { z } from 'zod';
- *
- * const UserSchema = z.object({
- *   id: z.string().uuid(),
- *   name: z.string(),
- *   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 [];
- *   }
- * }
- *
- * const app = await Rikta.create({ port: 3000 });
- *
- * // Register swagger plugin
- * app.server.register(swaggerPlugin, {
- *   title: 'My API',
- *   version: '1.0.0',
- *   description: 'My awesome API documentation',
- * });
- *
- * await app.listen();
- * // Swagger UI available at http://localhost:3000/docs
- * // OpenAPI JSON available at http://localhost:3000/docs/json
- * ```
- *
- * @packageDocumentation
- */
-// Export swagger-specific constants
 export * from './constants.js';
-// Re-export core constants needed for metadata reading
-// These are imported from @riktajs/core to avoid duplication
 export { CONTROLLER_METADATA, ROUTES_METADATA, PARAM_METADATA, HTTP_CODE_METADATA, GUARDS_METADATA, ZOD_SCHEMA_METADATA, } from '@riktajs/core';
-// Export decorators
 export * from './decorators/index.js';
-// Export OpenAPI generator
 export { OpenApiGenerator } from './openapi/generator.js';
-// Export Zod-to-OpenAPI utilities
 export { zodToOpenApi, toOpenApiSchema, isZodSchema } from './openapi/zod-to-openapi.js';
-// Export Fastify plugin
 export { swaggerPlugin, registerSwagger, createSwaggerConfig } from './plugin/swagger.plugin.js';
-//# sourceMappingURL=index.js.map

package/dist/openapi/generator.d.ts

@@ -1,68 +1,23 @@
 import 'reflect-metadata';
 import type { SwaggerConfig, OpenApiDocument, OpenApiSecurityScheme, OpenApiInfoObject } from '../types.js';
 type Constructor<T = unknown> = new (...args: any[]) => T;
-/**
- * Shorthand config options that allow flat title/version/description
- */
 interface OpenApiGeneratorConfig extends Omit<SwaggerConfig, 'info'> {
-    /** API title (shorthand for info.title) */
     title?: string;
-    /** API version (shorthand for info.version) */
     version?: string;
-    /** API description (shorthand for info.description) */
     description?: string;
-    /** API contact (shorthand for info.contact) */
     contact?: OpenApiInfoObject['contact'];
-    /** API license (shorthand for info.license) */
     license?: OpenApiInfoObject['license'];
-    /** API terms of service (shorthand for info.termsOfService) */
     termsOfService?: string;
-    /** Full info object (takes precedence over shorthand) */
     info?: OpenApiInfoObject;
 }
-/**
- * OpenAPI Specification Generator
- *
- * Collects metadata from controllers and generates a complete
- * OpenAPI 3.0.3 specification document.
- *
- * @example
- * ```typescript
- * const generator = new OpenApiGenerator({
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *   },
- * });
- *
- * // Add controllers to scan
- * generator.addController(UserController);
- * generator.addController(ProductController);
- *
- * // Generate the specification
- * const spec = generator.generate();
- * ```
- */
 export declare class OpenApiGenerator {
     private config;
     private controllers;
     private globalSecuritySchemes;
     constructor(config?: OpenApiGeneratorConfig);
-    /**
-     * Add a controller to be documented
-     */
     addController(controller: Constructor): this;
-    /**
-     * Add multiple controllers
-     */
     addControllers(controllers: Constructor[]): this;
-    /**
-     * Add a global security scheme
-     */
     addSecurityScheme(name: string, scheme: OpenApiSecurityScheme): this;
-    /**
-     * Generate the OpenAPI specification document
-     */
     generate(): OpenApiDocument;
     private getControllerMeta;
     private getControllerRoutes;
@@ -90,9 +45,5 @@ export declare class OpenApiGenerator {
     private getDefaultStatusDescription;
     private buildSecuritySchemes;
 }
-/**
- * Create a new OpenAPI generator instance
- */
 export declare function createOpenApiGenerator(config?: Partial<SwaggerConfig>): OpenApiGenerator;
 export {};
-//# sourceMappingURL=generator.d.ts.map

package/dist/openapi/generator.js

@@ -1,47 +1,18 @@
 import 'reflect-metadata';
-import { ParamType, 
-// Metadata helper functions
-getControllerMetadata, getRoutes, getParamMetadata as getCoreParamMetadata, getHttpCode, getClassMetadata, getMethodMetadata, } from '@riktajs/core';
+import { ParamType, getControllerMetadata, getRoutes, getParamMetadata as getCoreParamMetadata, getHttpCode, getClassMetadata, getMethodMetadata, } from '@riktajs/core';
 import { API_TAGS_METADATA, API_OPERATION_METADATA, API_RESPONSE_METADATA, API_BODY_METADATA, API_PARAM_METADATA, API_QUERY_METADATA, API_HEADER_METADATA, API_SECURITY_METADATA, API_EXCLUDE_METADATA, API_DEPRECATED_METADATA, } from '../constants.js';
 import { zodToOpenApi, toOpenApiSchema } from './zod-to-openapi.js';
-/**
- * Default swagger config values
- */
 const DEFAULT_SWAGGER_CONFIG = {
     info: {
         title: 'API Documentation',
         version: '1.0.0',
     },
 };
-/**
- * OpenAPI Specification Generator
- *
- * Collects metadata from controllers and generates a complete
- * OpenAPI 3.0.3 specification document.
- *
- * @example
- * ```typescript
- * const generator = new OpenApiGenerator({
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *   },
- * });
- *
- * // Add controllers to scan
- * generator.addController(UserController);
- * generator.addController(ProductController);
- *
- * // Generate the specification
- * const spec = generator.generate();
- * ```
- */
 export class OpenApiGenerator {
     config;
     controllers = [];
     globalSecuritySchemes = new Map();
     constructor(config = {}) {
-        // Build info object from shorthand or full info
         const info = config.info ?? {
             title: config.title ?? DEFAULT_SWAGGER_CONFIG.info?.title ?? 'API Documentation',
             version: config.version ?? DEFAULT_SWAGGER_CONFIG.info?.version ?? '1.0.0',
@@ -50,7 +21,6 @@ export class OpenApiGenerator {
             license: config.license,
             termsOfService: config.termsOfService,
         };
-        // Extract remaining config (excluding shorthand properties)
         const { title, version, description, contact, license, termsOfService, ...restConfig } = config;
         this.config = {
             ...DEFAULT_SWAGGER_CONFIG,
@@ -58,36 +28,23 @@ export class OpenApiGenerator {
             info,
         };
     }
-    /**
-     * Add a controller to be documented
-     */
     addController(controller) {
         this.controllers.push(controller);
         return this;
     }
-    /**
-     * Add multiple controllers
-     */
     addControllers(controllers) {
         this.controllers.push(...controllers);
         return this;
     }
-    /**
-     * Add a global security scheme
-     */
     addSecurityScheme(name, scheme) {
         this.globalSecuritySchemes.set(name, scheme);
         return this;
     }
-    /**
-     * Generate the OpenAPI specification document
-     */
     generate() {
         const paths = {};
         const tags = [];
         const seenTags = new Set();
         for (const controller of this.controllers) {
-            // Check if controller is excluded
             if (this.isControllerExcluded(controller)) {
                 continue;
             }
@@ -96,17 +53,14 @@ export class OpenApiGenerator {
                 continue;
             const controllerTags = this.getControllerTags(controller);
             const controllerDeprecated = this.isControllerDeprecated(controller);
-            // Add controller tags to the global tags list
             for (const tag of controllerTags) {
                 if (!seenTags.has(tag)) {
                     seenTags.add(tag);
                     tags.push({ name: tag });
                 }
             }
-            // Process each route
             const routes = this.getControllerRoutes(controller);
             for (const route of routes) {
-                // Check if endpoint is excluded
                 if (this.isEndpointExcluded(controller, route.handlerName)) {
                     continue;
                 }
@@ -116,11 +70,9 @@ export class OpenApiGenerator {
                     paths[fullPath] = {};
                 }
                 const operation = this.buildOperation(controller, route, controllerTags, controllerDeprecated);
-                // Assign operation to the path item using method as key
                 paths[fullPath][method] = operation;
             }
         }
-        // Build security schemes from global and controller-level definitions
         const securitySchemes = this.buildSecuritySchemes();
         const document = {
             openapi: '3.0.3',
@@ -144,9 +96,6 @@ export class OpenApiGenerator {
         }
         return document;
     }
-    // ============================================================================
-    // Private: Metadata Getters (using core helpers)
-    // ============================================================================
     getControllerMeta(controller) {
         return getControllerMetadata(controller);
     }
@@ -192,14 +141,12 @@ export class OpenApiGenerator {
         const controllerLevel = getClassMetadata(API_SECURITY_METADATA, controller);
         const methodLevel = getMethodMetadata(API_SECURITY_METADATA, controller, handlerName);
         const result = [];
-        // Controller level can be a single object or null (to remove security)
         if (controllerLevel && typeof controllerLevel === 'object' && 'name' in controllerLevel) {
             result.push(controllerLevel);
         }
         else if (Array.isArray(controllerLevel)) {
             result.push(...controllerLevel);
         }
-        // Method level can override or add to controller level
         if (methodLevel && typeof methodLevel === 'object' && 'name' in methodLevel) {
             result.push(methodLevel);
         }
@@ -218,11 +165,7 @@ export class OpenApiGenerator {
     getCoreParams(controller, handlerName) {
         return getCoreParamMetadata(controller, handlerName);
     }
-    // ============================================================================
-    // Private: Path Utilities
-    // ============================================================================
     normalizePath(prefix, path) {
-        // Ensure prefix starts with / and path handling
         let fullPath = '';
         if (prefix) {
             fullPath = prefix.startsWith('/') ? prefix : `/${prefix}`;
@@ -231,21 +174,15 @@ export class OpenApiGenerator {
             const cleanPath = path.startsWith('/') ? path : `/${path}`;
             fullPath = fullPath + cleanPath;
         }
-        // Handle root path
         if (!fullPath) {
             fullPath = '/';
         }
-        // Convert :param to {param} (Fastify to OpenAPI format)
         fullPath = fullPath.replace(/:([^/]+)/g, '{$1}');
-        // Remove trailing slash (except for root)
         if (fullPath !== '/' && fullPath.endsWith('/')) {
             fullPath = fullPath.slice(0, -1);
         }
         return fullPath;
     }
-    // ============================================================================
-    // Private: Operation Builder
-    // ============================================================================
     buildOperation(controller, route, controllerTags, controllerDeprecated) {
         const handlerName = route.handlerName;
         const operationMeta = this.getOperationMetadata(controller, handlerName);
@@ -253,12 +190,10 @@ export class OpenApiGenerator {
         const operation = {
             responses: {},
         };
-        // Tags (method level overrides controller level)
         const tags = methodTags || controllerTags;
         if (tags.length > 0) {
             operation.tags = tags;
         }
-        // Summary and description from @ApiOperation
         if (operationMeta?.summary) {
             operation.summary = operationMeta.summary;
         }
@@ -268,25 +203,20 @@ export class OpenApiGenerator {
         if (operationMeta?.operationId) {
             operation.operationId = operationMeta.operationId;
         }
-        // Deprecated flag
         if (controllerDeprecated || operationMeta?.deprecated || this.isEndpointDeprecated(controller, handlerName)) {
             operation.deprecated = true;
         }
-        // Parameters (path, query, header)
         const parameters = this.buildParameters(controller, handlerName, route.path);
         if (parameters.length > 0) {
             operation.parameters = parameters;
         }
-        // Request body (for POST, PUT, PATCH)
         if (['POST', 'PUT', 'PATCH'].includes(route.method)) {
             const requestBody = this.buildRequestBody(controller, handlerName);
             if (requestBody) {
                 operation.requestBody = requestBody;
             }
         }
-        // Responses
         operation.responses = this.buildResponses(controller, handlerName, route.statusCode);
-        // Security
         const security = this.getSecurityMetadata(controller, handlerName);
         if (security.length > 0) {
             operation.security = security.map(s => ({ [s.name]: s.scopes || [] }));
@@ -295,13 +225,11 @@ export class OpenApiGenerator {
     }
     buildParameters(controller, handlerName, routePath) {
         const parameters = [];
-        // Extract path parameters from route pattern
         const pathParams = this.extractPathParams(routePath);
         const paramDecorators = this.getSwaggerParamMetadata(controller, handlerName);
         const queryDecorators = this.getQueryMetadata(controller, handlerName);
         const headerDecorators = this.getHeaderMetadata(controller, handlerName);
         const coreParams = this.getCoreParams(controller, handlerName);
-        // Add path parameters from decorator metadata or extract from path
         const usedPathParams = new Set();
         for (const param of paramDecorators) {
             usedPathParams.add(param.name);
@@ -315,17 +243,15 @@ export class OpenApiGenerator {
             parameters.push({
                 name: param.name,
                 in: 'path',
-                required: true, // Path params are always required
+                required: true,
                 deprecated: param.deprecated,
                 description: param.description,
                 schema: baseSchema || fallbackSchema,
                 example: param.example,
             });
         }
-        // Add any path parameters not covered by decorators
         for (const paramName of pathParams) {
             if (!usedPathParams.has(paramName)) {
-                // Check if there's a Zod schema for this parameter
                 const coreParam = coreParams.find(p => p.type === ParamType.PARAM && p.key === paramName);
                 const schema = coreParam?.zodSchema ? zodToOpenApi(coreParam.zodSchema) : { type: 'string' };
                 parameters.push({
@@ -336,7 +262,6 @@ export class OpenApiGenerator {
                 });
             }
         }
-        // Add query parameters
         for (const query of queryDecorators) {
             const baseSchema = toOpenApiSchema(query.schema);
             const fallbackSchema = {
@@ -355,7 +280,6 @@ export class OpenApiGenerator {
                 example: query.example,
             });
         }
-        // Add header parameters
         for (const header of headerDecorators) {
             parameters.push({
                 name: header.name,
@@ -373,7 +297,6 @@ export class OpenApiGenerator {
     }
     extractPathParams(path) {
         const params = [];
-        // Match both :param (Fastify) and {param} (OpenAPI) formats
         const regex = /:([^/]+)|{([^}]+)}/g;
         let match;
         while ((match = regex.exec(path)) !== null) {
@@ -387,7 +310,6 @@ export class OpenApiGenerator {
     buildRequestBody(controller, handlerName) {
         const bodyMeta = this.getBodyMetadata(controller, handlerName);
         const coreParams = this.getCoreParams(controller, handlerName);
-        // Check for @ApiBody decorator first
         if (bodyMeta) {
             const schema = toOpenApiSchema(bodyMeta.schema);
             return {
@@ -401,7 +323,6 @@ export class OpenApiGenerator {
                 },
             };
         }
-        // Fallback: check for @Body() decorator with Zod schema
         const bodyParam = coreParams.find(p => p.type === ParamType.BODY);
         if (bodyParam?.zodSchema) {
             return {
@@ -437,7 +358,6 @@ export class OpenApiGenerator {
             }
         }
         else {
-            // Add default response based on HTTP code
             const status = (httpCode || defaultStatusCode || 200).toString();
             responses[status] = {
                 description: this.getDefaultStatusDescription(Number(status)),
@@ -484,10 +404,6 @@ export class OpenApiGenerator {
         return schemes;
     }
 }
-/**
- * Create a new OpenAPI generator instance
- */
 export function createOpenApiGenerator(config) {
     return new OpenApiGenerator(config);
 }
-//# sourceMappingURL=generator.js.map

package/dist/openapi/index.d.ts

@@ -1,8 +1,2 @@
-/**
- * OpenAPI generation utilities barrel export
- *
- * @packageDocumentation
- */
 export { zodToOpenApi, isZodSchema, toOpenApiSchema } from './zod-to-openapi.js';
 export { OpenApiGenerator, createOpenApiGenerator } from './generator.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/openapi/index.js

@@ -1,11 +1,2 @@
-/**
- * OpenAPI generation utilities barrel export
- *
- * @packageDocumentation
- */
-// Zod to OpenAPI converter
 export { zodToOpenApi, isZodSchema, toOpenApiSchema } from './zod-to-openapi.js';
-// OpenAPI specification generator
 export { OpenApiGenerator, createOpenApiGenerator } from './generator.js';
-// export * from './generator.js';
-//# sourceMappingURL=index.js.map

package/dist/openapi/zod-to-openapi.d.ts

@@ -1,52 +1,5 @@
-import type { ZodType, ZodTypeDef } from 'zod';
+import { type ZodType } from 'zod';
 import type { OpenApiSchemaObject } from '../types.js';
-/**
- * Type guard to check if a value is a Zod schema
- * Uses duck typing to detect Zod schemas without requiring the full library
- */
-export declare function isZodSchema(value: unknown): value is ZodType<unknown, ZodTypeDef, unknown>;
-/**
- * Convert a Zod schema to an OpenAPI 3.0 schema object
- *
- * Uses `zod-to-json-schema` for the heavy lifting, then converts
- * JSON Schema 7 to OpenAPI 3.0 compatible format.
- *
- * Supports all Zod types including:
- * - 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
- * - Literals
- * - Effects (transform, refine)
- *
- * @param schema - The Zod schema to convert
- * @returns OpenAPI schema object
- *
- * @example
- * ```typescript
- * const UserSchema = z.object({
- *   id: z.string().uuid(),
- *   email: z.string().email(),
- *   age: z.number().int().min(0).optional(),
- * });
- *
- * const openApiSchema = zodToOpenApi(UserSchema);
- * // {
- * //   type: 'object',
- * //   properties: {
- * //     id: { type: 'string', format: 'uuid' },
- * //     email: { type: 'string', format: 'email' },
- * //     age: { type: 'integer', minimum: 0 }
- * //   },
- * //   required: ['id', 'email']
- * // }
- * ```
- */
+export declare function isZodSchema(value: unknown): value is ZodType<unknown>;
 export declare function zodToOpenApi(schema: ZodType): OpenApiSchemaObject;
-/**
- * Convert a Zod schema to OpenAPI schema, or pass through if already an OpenAPI schema
- */
 export declare function toOpenApiSchema(schemaOrOpenApi: ZodType | OpenApiSchemaObject | undefined): OpenApiSchemaObject | undefined;
-//# sourceMappingURL=zod-to-openapi.d.ts.map