@riktajs/swagger 0.1.1 → 0.1.3

package/dist/openapi/zod-to-openapi.js

@@ -1,8 +1,4 @@
 import { zodToJsonSchema } from 'zod-to-json-schema';
-/**
- * Type guard to check if a value is a Zod schema
- * Uses duck typing to detect Zod schemas without requiring the full library
- */
 export function isZodSchema(value) {
     return (value !== null &&
         typeof value === 'object' &&
@@ -10,21 +6,12 @@ export function isZodSchema(value) {
         'safeParse' in value &&
         typeof value.safeParse === 'function');
 }
-/**
- * Convert JSON Schema 7 to OpenAPI 3.0 compatible schema
- *
- * Main differences:
- * - OpenAPI uses `nullable: true` instead of `type: ['string', 'null']`
- * - OpenAPI 3.0 doesn't support `$schema`, `$id`, etc.
- * - Some JSON Schema features need to be simplified
- */
 function jsonSchemaToOpenApi(jsonSchema) {
     if (typeof jsonSchema === 'boolean') {
         return jsonSchema ? {} : { not: {} };
     }
     const result = {};
     const schema = jsonSchema;
-    // Handle type with null (convert to nullable)
     if (Array.isArray(schema.type)) {
         const types = schema.type;
         const nullIndex = types.indexOf('null');
@@ -35,7 +22,6 @@ function jsonSchemaToOpenApi(jsonSchema) {
                 result.type = nonNullTypes[0];
             }
             else if (nonNullTypes.length > 1) {
-                // Multiple non-null types - use oneOf
                 result.oneOf = nonNullTypes.map(t => ({ type: t }));
             }
         }
@@ -46,7 +32,6 @@ function jsonSchemaToOpenApi(jsonSchema) {
     else if (schema.type) {
         result.type = schema.type;
     }
-    // Copy simple properties
     const simpleProps = [
         'format', 'description', 'default', 'example', 'enum',
         'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum',
@@ -60,24 +45,20 @@ function jsonSchemaToOpenApi(jsonSchema) {
             result[prop] = schema[prop];
         }
     }
-    // Handle items (for arrays)
     if (schema.items) {
         if (Array.isArray(schema.items)) {
-            // Tuple - OpenAPI 3.0 doesn't support tuple validation well
             result.items = { oneOf: schema.items.map(jsonSchemaToOpenApi) };
         }
         else {
             result.items = jsonSchemaToOpenApi(schema.items);
         }
     }
-    // Handle properties (for objects)
     if (schema.properties) {
         result.properties = {};
         for (const [key, value] of Object.entries(schema.properties)) {
             result.properties[key] = jsonSchemaToOpenApi(value);
         }
     }
-    // Handle additionalProperties
     if (schema.additionalProperties !== undefined) {
         if (typeof schema.additionalProperties === 'boolean') {
             result.additionalProperties = schema.additionalProperties;
@@ -86,7 +67,6 @@ function jsonSchemaToOpenApi(jsonSchema) {
             result.additionalProperties = jsonSchemaToOpenApi(schema.additionalProperties);
         }
     }
-    // Handle allOf, oneOf, anyOf
     if (schema.allOf) {
         result.allOf = schema.allOf.map(jsonSchemaToOpenApi);
     }
@@ -96,69 +76,21 @@ function jsonSchemaToOpenApi(jsonSchema) {
     if (schema.anyOf) {
         result.anyOf = schema.anyOf.map(jsonSchemaToOpenApi);
     }
-    // Handle not
     if (schema.not) {
         result.not = jsonSchemaToOpenApi(schema.not);
     }
-    // Handle const (convert to enum with single value)
     if (schema.const !== undefined) {
         result.enum = [schema.const];
     }
     return result;
 }
-/**
- * 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 function zodToOpenApi(schema) {
-    // Convert to JSON Schema using zod-to-json-schema
     const jsonSchema = zodToJsonSchema(schema, {
         target: 'openApi3',
-        $refStrategy: 'none', // Inline all references
+        $refStrategy: 'none',
     });
-    // Convert JSON Schema to OpenAPI format
-    // The result from zodToJsonSchema may include $schema and definitions
-    // which are not part of JsonSchema7Type but are compatible
     return jsonSchemaToOpenApi(jsonSchema);
 }
-/**
- * Convert a Zod schema to OpenAPI schema, or pass through if already an OpenAPI schema
- */
 export function toOpenApiSchema(schemaOrOpenApi) {
     if (!schemaOrOpenApi) {
         return undefined;
@@ -166,7 +98,5 @@ export function toOpenApiSchema(schemaOrOpenApi) {
     if (isZodSchema(schemaOrOpenApi)) {
         return zodToOpenApi(schemaOrOpenApi);
     }
-    // Already an OpenAPI schema object
     return schemaOrOpenApi;
 }
-//# sourceMappingURL=zod-to-openapi.js.map

package/dist/plugin/index.d.ts

@@ -1,7 +1 @@
-/**
- * Swagger Plugin barrel export
- *
- * @packageDocumentation
- */
 export { swaggerPlugin, registerSwagger, createSwaggerConfig, type SwaggerPluginOptions, } from './swagger.plugin.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.js

@@ -1,7 +1 @@
-/**
- * Swagger Plugin barrel export
- *
- * @packageDocumentation
- */
 export { swaggerPlugin, registerSwagger, createSwaggerConfig, } from './swagger.plugin.js';
-//# sourceMappingURL=index.js.map

package/dist/plugin/swagger.plugin.d.ts

@@ -2,59 +2,20 @@ import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
 import { type FastifySwaggerUiOptions } from '@fastify/swagger-ui';
 import type { SwaggerConfig, OpenApiDocument, OpenApiInfoObject } from '../types.js';
 type Constructor<T = unknown> = new (...args: any[]) => T;
-/**
- * Swagger plugin options
- */
 export interface SwaggerPluginOptions {
-    /**
-     * Swagger/OpenAPI configuration
-     */
     config?: SwaggerConfig;
-    /**
-     * API Info (title, version, description, etc.)
-     * Can also be provided via config.info
-     */
     info?: OpenApiInfoObject;
-    /**
-     * Controllers to document (optional - will auto-discover from registry if not provided)
-     */
     controllers?: Constructor[];
-    /**
-     * Path to serve the OpenAPI JSON specification
-     * @default '/docs/json'
-     */
     jsonPath?: string;
-    /**
-     * Path to serve the Swagger UI
-     * @default '/docs'
-     */
     uiPath?: string;
-    /**
-     * Whether to expose the Swagger UI
-     * @default true
-     */
     exposeUI?: boolean;
-    /**
-     * Whether to expose the OpenAPI JSON specification
-     * @default true
-     */
     exposeSpec?: boolean;
-    /**
-     * Logo configuration for Swagger UI
-     */
     logo?: {
         url: string;
         altText?: string;
         backgroundColor?: string;
     };
-    /**
-     * Swagger UI theme
-     * @default 'default'
-     */
     theme?: 'default' | 'dark';
-    /**
-     * Transform the OpenAPI specification before serving
-     */
     transform?: (spec: OpenApiDocument) => OpenApiDocument | Promise<OpenApiDocument>;
 }
 declare module 'fastify' {
@@ -62,87 +23,8 @@ declare module 'fastify' {
         openApiSpec?: OpenApiDocument;
     }
 }
-/**
- * Swagger plugin for Fastify/Rikta
- *
- * Automatically generates OpenAPI documentation from Rikta controllers
- * and serves Swagger UI for interactive API exploration.
- *
- * @example
- * ```typescript
- * import { RiktaFactory } from '@riktajs/core';
- * import { swaggerPlugin } from '@riktajs/swagger';
- *
- * const app = await RiktaFactory.create();
- *
- * await app.register(swaggerPlugin, {
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *     description: 'API documentation for My App',
- *   },
- *   config: {
- *     servers: [
- *       { url: 'http://localhost:3000', description: 'Development' },
- *     ],
- *   },
- * });
- *
- * // Swagger UI available at /docs
- * // OpenAPI JSON at /docs/json
- * ```
- */
 export declare const swaggerPlugin: FastifyPluginAsync<SwaggerPluginOptions>;
-/**
- * Register swagger plugin with a Rikta application
- *
- * Helper function that provides a simpler API for registering the plugin.
- *
- * @param app - Fastify instance
- * @param options - Swagger plugin options
- *
- * @example
- * ```typescript
- * import { RiktaFactory } from '@riktajs/core';
- * import { registerSwagger } from '@riktajs/swagger';
- *
- * const app = await RiktaFactory.create();
- *
- * await registerSwagger(app, {
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *   },
- * });
- * ```
- */
 export declare function registerSwagger(app: FastifyInstance, options?: SwaggerPluginOptions): Promise<void>;
-/**
- * Create a standalone Swagger configuration for manual use
- *
- * Use this when you need more control over the Swagger setup,
- * or when integrating with an existing Fastify application.
- *
- * @param options - Swagger plugin options
- * @returns Object containing swagger and swaggerUI options and specification
- *
- * @example
- * ```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);
- * ```
- */
 export declare function createSwaggerConfig(options?: SwaggerPluginOptions): {
     swaggerOptions: {
         mode: 'static';
@@ -154,4 +36,3 @@ export declare function createSwaggerConfig(options?: SwaggerPluginOptions): {
     specification: OpenApiDocument;
 };
 export {};
-//# sourceMappingURL=swagger.plugin.d.ts.map

package/dist/plugin/swagger.plugin.js

@@ -3,60 +3,42 @@ import fastifySwagger from '@fastify/swagger';
 import fastifySwaggerUI from '@fastify/swagger-ui';
 import { OpenApiGenerator } from '../openapi/generator.js';
 import { registry } from '@riktajs/core';
-/**
- * Default plugin options
- */
 const DEFAULT_OPTIONS = {
     jsonPath: '/docs/json',
     uiPath: '/docs',
     exposeUI: true,
     exposeSpec: true,
 };
-/**
- * Swagger plugin implementation
- *
- * Registers @fastify/swagger and @fastify/swagger-ui with automatic
- * OpenAPI specification generation from Rikta controllers.
- */
 async function swaggerPluginImpl(fastify, options) {
     const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
     const { jsonPath, uiPath, exposeUI, exposeSpec, controllers, config, info, transform } = mergedOptions;
-    // Build info object from options or config
     const apiInfo = info || config?.info || {
         title: 'API Documentation',
         version: '1.0.0',
     };
-    // Create OpenAPI generator
     const generator = new OpenApiGenerator({
         ...config,
         info: apiInfo,
     });
-    // Get controllers to document
     const controllersToDocument = controllers || registry.getControllers();
-    // Add controllers to generator
     for (const controller of controllersToDocument) {
         generator.addController(controller);
     }
-    // Add security schemes from config
     if (config?.securitySchemes) {
         for (const [name, scheme] of Object.entries(config.securitySchemes)) {
             generator.addSecurityScheme(name, scheme);
         }
     }
-    // Generate OpenAPI specification
     let spec = generator.generate();
-    // Apply transform if provided
     if (transform) {
         spec = await transform(spec);
     }
-    // Register @fastify/swagger with static specification
     await fastify.register(fastifySwagger, {
         mode: 'static',
         specification: {
-            document: spec, // Type assertion needed due to fastify-swagger types
+            document: spec,
         },
     });
-    // Register @fastify/swagger-ui if enabled
     if (exposeUI) {
         const uiOptions = {
             routePrefix: uiPath,
@@ -73,7 +55,6 @@ async function swaggerPluginImpl(fastify, options) {
             staticCSP: true,
             transformStaticCSP: (header) => header,
         };
-        // Add logo if provided
         if (mergedOptions.logo) {
             uiOptions.logo = {
                 type: 'image/png',
@@ -83,11 +64,6 @@ async function swaggerPluginImpl(fastify, options) {
         }
         await fastify.register(fastifySwaggerUI, uiOptions);
     }
-    // Add JSON spec route if enabled
-    // @fastify/swagger-ui registers routes at {uiPath}/json when UI is enabled
-    // So we only add custom route if:
-    // 1. UI is disabled (no swagger-ui default route exists)
-    // 2. jsonPath differs from swagger-ui default path
     const defaultSwaggerUIJsonPath = `${uiPath}/json`;
     const shouldRegisterCustomJsonRoute = exposeSpec && (!exposeUI ||
         (jsonPath !== defaultSwaggerUIJsonPath && jsonPath !== '/docs/json'));
@@ -100,115 +76,31 @@ async function swaggerPluginImpl(fastify, options) {
             return spec;
         });
     }
-    // Store spec on fastify instance for later access
     fastify.decorate('openApiSpec', spec);
 }
-/**
- * Swagger plugin for Fastify/Rikta
- *
- * Automatically generates OpenAPI documentation from Rikta controllers
- * and serves Swagger UI for interactive API exploration.
- *
- * @example
- * ```typescript
- * import { RiktaFactory } from '@riktajs/core';
- * import { swaggerPlugin } from '@riktajs/swagger';
- *
- * const app = await RiktaFactory.create();
- *
- * await app.register(swaggerPlugin, {
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *     description: 'API documentation for My App',
- *   },
- *   config: {
- *     servers: [
- *       { url: 'http://localhost:3000', description: 'Development' },
- *     ],
- *   },
- * });
- *
- * // Swagger UI available at /docs
- * // OpenAPI JSON at /docs/json
- * ```
- */
 export const swaggerPlugin = fp(swaggerPluginImpl, {
     fastify: '>=4.0.0',
     name: '@riktajs/swagger',
     dependencies: [],
 });
-/**
- * Register swagger plugin with a Rikta application
- *
- * Helper function that provides a simpler API for registering the plugin.
- *
- * @param app - Fastify instance
- * @param options - Swagger plugin options
- *
- * @example
- * ```typescript
- * import { RiktaFactory } from '@riktajs/core';
- * import { registerSwagger } from '@riktajs/swagger';
- *
- * const app = await RiktaFactory.create();
- *
- * await registerSwagger(app, {
- *   info: {
- *     title: 'My API',
- *     version: '1.0.0',
- *   },
- * });
- * ```
- */
 export async function registerSwagger(app, options = {}) {
     await app.register(swaggerPlugin, options);
 }
-/**
- * Create a standalone Swagger configuration for manual use
- *
- * Use this when you need more control over the Swagger setup,
- * or when integrating with an existing Fastify application.
- *
- * @param options - Swagger plugin options
- * @returns Object containing swagger and swaggerUI options and specification
- *
- * @example
- * ```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);
- * ```
- */
 export function createSwaggerConfig(options = {}) {
     const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
     const { uiPath, controllers, config, info } = mergedOptions;
-    // Build info object
     const apiInfo = info || config?.info || {
         title: 'API Documentation',
         version: '1.0.0',
     };
-    // Create generator
     const generator = new OpenApiGenerator({
         ...config,
         info: apiInfo,
     });
-    // Add controllers
     const controllersToDocument = controllers || registry.getControllers();
     for (const controller of controllersToDocument) {
         generator.addController(controller);
     }
-    // Add security schemes
     if (config?.securitySchemes) {
         for (const [name, scheme] of Object.entries(config.securitySchemes)) {
             generator.addSecurityScheme(name, scheme);
@@ -232,4 +124,3 @@ export function createSwaggerConfig(options = {}) {
         specification,
     };
 }
-//# sourceMappingURL=swagger.plugin.js.map