@riktajs/swagger 0.10.2 → 0.11.0

package/dist/index.js

@@ -1,6 +1,1163 @@
-export * from './constants.js';
-export { CONTROLLER_METADATA, ROUTES_METADATA, PARAM_METADATA, HTTP_CODE_METADATA, GUARDS_METADATA, ZOD_SCHEMA_METADATA, } from '@riktajs/core';
-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';
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/constants.ts
+var API_TAGS_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiTags");
+var API_OPERATION_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiOperation");
+var API_RESPONSE_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiResponse");
+var API_PROPERTY_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiProperty");
+var API_BODY_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiBody");
+var API_PARAM_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiParam");
+var API_QUERY_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiQuery");
+var API_HEADER_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiHeader");
+var API_SECURITY_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiSecurity");
+var API_EXCLUDE_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiExclude");
+var API_DEPRECATED_METADATA = /* @__PURE__ */ Symbol.for("rikta:swagger:apiDeprecated");
+
+// src/index.ts
+import { CONTROLLER_METADATA, ROUTES_METADATA, PARAM_METADATA, HTTP_CODE_METADATA, GUARDS_METADATA, ZOD_SCHEMA_METADATA } from "@riktajs/core";
+
+// src/decorators/api-tags.decorator.ts
+import "reflect-metadata";
+function ApiTags(...tags) {
+  return (target, propertyKey, descriptor) => {
+    if (propertyKey !== void 0 && descriptor !== void 0) {
+      const existingTags = Reflect.getMetadata(API_TAGS_METADATA, target, propertyKey) ?? [];
+      Reflect.defineMetadata(API_TAGS_METADATA, [
+        ...existingTags,
+        ...tags
+      ], target, propertyKey);
+    } else {
+      const existingTags = Reflect.getMetadata(API_TAGS_METADATA, target) ?? [];
+      Reflect.defineMetadata(API_TAGS_METADATA, [
+        ...existingTags,
+        ...tags
+      ], target);
+    }
+  };
+}
+__name(ApiTags, "ApiTags");
+function getApiTags(target, propertyKey) {
+  if (propertyKey !== void 0) {
+    const methodTags = Reflect.getMetadata(API_TAGS_METADATA, target.prototype, propertyKey) ?? [];
+    const classTags = Reflect.getMetadata(API_TAGS_METADATA, target) ?? [];
+    return [
+      .../* @__PURE__ */ new Set([
+        ...classTags,
+        ...methodTags
+      ])
+    ];
+  }
+  return Reflect.getMetadata(API_TAGS_METADATA, target) ?? [];
+}
+__name(getApiTags, "getApiTags");
+
+// src/decorators/api-operation.decorator.ts
+import "reflect-metadata";
+function ApiOperation(options) {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(API_OPERATION_METADATA, options, target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiOperation, "ApiOperation");
+function getApiOperation(target, propertyKey) {
+  return Reflect.getMetadata(API_OPERATION_METADATA, target.prototype, propertyKey);
+}
+__name(getApiOperation, "getApiOperation");
+
+// src/decorators/api-response.decorator.ts
+import "reflect-metadata";
+function ApiResponse(options) {
+  return (target, propertyKey, descriptor) => {
+    const existingResponses = Reflect.getMetadata(API_RESPONSE_METADATA, target, propertyKey) ?? [];
+    Reflect.defineMetadata(API_RESPONSE_METADATA, [
+      ...existingResponses,
+      options
+    ], target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiResponse, "ApiResponse");
+function ApiOkResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 200
+  });
+}
+__name(ApiOkResponse, "ApiOkResponse");
+function ApiCreatedResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 201
+  });
+}
+__name(ApiCreatedResponse, "ApiCreatedResponse");
+function ApiAcceptedResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 202
+  });
+}
+__name(ApiAcceptedResponse, "ApiAcceptedResponse");
+function ApiNoContentResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 204
+  });
+}
+__name(ApiNoContentResponse, "ApiNoContentResponse");
+function ApiBadRequestResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 400,
+    description: options.description ?? "Bad Request"
+  });
+}
+__name(ApiBadRequestResponse, "ApiBadRequestResponse");
+function ApiUnauthorizedResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 401,
+    description: options.description ?? "Unauthorized"
+  });
+}
+__name(ApiUnauthorizedResponse, "ApiUnauthorizedResponse");
+function ApiForbiddenResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 403,
+    description: options.description ?? "Forbidden"
+  });
+}
+__name(ApiForbiddenResponse, "ApiForbiddenResponse");
+function ApiNotFoundResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 404,
+    description: options.description ?? "Not Found"
+  });
+}
+__name(ApiNotFoundResponse, "ApiNotFoundResponse");
+function ApiConflictResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 409,
+    description: options.description ?? "Conflict"
+  });
+}
+__name(ApiConflictResponse, "ApiConflictResponse");
+function ApiUnprocessableEntityResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 422,
+    description: options.description ?? "Unprocessable Entity"
+  });
+}
+__name(ApiUnprocessableEntityResponse, "ApiUnprocessableEntityResponse");
+function ApiInternalServerErrorResponse(options = {}) {
+  return ApiResponse({
+    ...options,
+    status: 500,
+    description: options.description ?? "Internal Server Error"
+  });
+}
+__name(ApiInternalServerErrorResponse, "ApiInternalServerErrorResponse");
+function getApiResponses(target, propertyKey) {
+  return Reflect.getMetadata(API_RESPONSE_METADATA, target.prototype, propertyKey) ?? [];
+}
+__name(getApiResponses, "getApiResponses");
+
+// src/decorators/api-body.decorator.ts
+import "reflect-metadata";
+function ApiBody(options) {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(API_BODY_METADATA, {
+      ...options,
+      required: options.required ?? true
+    }, target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiBody, "ApiBody");
+function getApiBody(target, propertyKey) {
+  return Reflect.getMetadata(API_BODY_METADATA, target.prototype, propertyKey);
+}
+__name(getApiBody, "getApiBody");
+
+// src/decorators/api-param.decorator.ts
+import "reflect-metadata";
+function ApiParam(options) {
+  return (target, propertyKey, descriptor) => {
+    const existingParams = Reflect.getMetadata(API_PARAM_METADATA, target, propertyKey) ?? [];
+    Reflect.defineMetadata(API_PARAM_METADATA, [
+      ...existingParams,
+      {
+        ...options,
+        required: options.required ?? true
+      }
+    ], target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiParam, "ApiParam");
+function getApiParams(target, propertyKey) {
+  return Reflect.getMetadata(API_PARAM_METADATA, target.prototype, propertyKey) ?? [];
+}
+__name(getApiParams, "getApiParams");
+
+// src/decorators/api-query.decorator.ts
+import "reflect-metadata";
+function ApiQuery(options) {
+  return (target, propertyKey, descriptor) => {
+    const existingQueries = Reflect.getMetadata(API_QUERY_METADATA, target, propertyKey) ?? [];
+    Reflect.defineMetadata(API_QUERY_METADATA, [
+      ...existingQueries,
+      {
+        ...options,
+        required: options.required ?? false
+      }
+    ], target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiQuery, "ApiQuery");
+function getApiQueries(target, propertyKey) {
+  return Reflect.getMetadata(API_QUERY_METADATA, target.prototype, propertyKey) ?? [];
+}
+__name(getApiQueries, "getApiQueries");
+
+// src/decorators/api-header.decorator.ts
+import "reflect-metadata";
+function ApiHeader(options) {
+  return (target, propertyKey, descriptor) => {
+    const existingHeaders = Reflect.getMetadata(API_HEADER_METADATA, target, propertyKey) ?? [];
+    Reflect.defineMetadata(API_HEADER_METADATA, [
+      ...existingHeaders,
+      options
+    ], target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiHeader, "ApiHeader");
+function getApiHeaders(target, propertyKey) {
+  return Reflect.getMetadata(API_HEADER_METADATA, target.prototype, propertyKey) ?? [];
+}
+__name(getApiHeaders, "getApiHeaders");
+
+// src/decorators/api-security.decorator.ts
+import "reflect-metadata";
+function ApiSecurity(name, scopes = []) {
+  return (target, propertyKey, descriptor) => {
+    const security = name ? {
+      name,
+      scopes
+    } : null;
+    if (propertyKey !== void 0 && descriptor !== void 0) {
+      Reflect.defineMetadata(API_SECURITY_METADATA, security, target, propertyKey);
+    } else {
+      Reflect.defineMetadata(API_SECURITY_METADATA, security, target);
+    }
+  };
+}
+__name(ApiSecurity, "ApiSecurity");
+function ApiBearerAuth(name = "bearerAuth") {
+  return ApiSecurity(name);
+}
+__name(ApiBearerAuth, "ApiBearerAuth");
+function ApiBasicAuth(name = "basicAuth") {
+  return ApiSecurity(name);
+}
+__name(ApiBasicAuth, "ApiBasicAuth");
+function ApiOAuth2(scopes = [], name = "oauth2") {
+  return ApiSecurity(name, scopes);
+}
+__name(ApiOAuth2, "ApiOAuth2");
+function ApiCookieAuth(name = "cookieAuth") {
+  return ApiSecurity(name);
+}
+__name(ApiCookieAuth, "ApiCookieAuth");
+function getApiSecurity(target, propertyKey) {
+  if (propertyKey !== void 0) {
+    const methodSecurity = Reflect.getMetadata(API_SECURITY_METADATA, target.prototype, propertyKey);
+    if (methodSecurity !== void 0) {
+      return methodSecurity;
+    }
+    return Reflect.getMetadata(API_SECURITY_METADATA, target);
+  }
+  return Reflect.getMetadata(API_SECURITY_METADATA, target);
+}
+__name(getApiSecurity, "getApiSecurity");
+
+// src/decorators/api-property.decorator.ts
+import "reflect-metadata";
+function ApiProperty(options = {}) {
+  return (target, propertyKey) => {
+    const existingProperties = Reflect.getMetadata(API_PROPERTY_METADATA, target.constructor) ?? [];
+    Reflect.defineMetadata(API_PROPERTY_METADATA, [
+      ...existingProperties,
+      {
+        propertyKey,
+        options
+      }
+    ], target.constructor);
+  };
+}
+__name(ApiProperty, "ApiProperty");
+function ApiPropertyOptional(options = {}) {
+  return ApiProperty({
+    ...options,
+    required: false
+  });
+}
+__name(ApiPropertyOptional, "ApiPropertyOptional");
+function ApiHideProperty() {
+  return (target, propertyKey) => {
+    const existingProperties = Reflect.getMetadata(API_PROPERTY_METADATA, target.constructor) ?? [];
+    Reflect.defineMetadata(API_PROPERTY_METADATA, [
+      ...existingProperties,
+      {
+        propertyKey,
+        options: {
+          _hidden: true
+        }
+      }
+    ], target.constructor);
+  };
+}
+__name(ApiHideProperty, "ApiHideProperty");
+function getApiProperties(target) {
+  return Reflect.getMetadata(API_PROPERTY_METADATA, target) ?? [];
+}
+__name(getApiProperties, "getApiProperties");
+
+// src/decorators/api-exclude.decorator.ts
+import "reflect-metadata";
+function ApiExcludeEndpoint() {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(API_EXCLUDE_METADATA, true, target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiExcludeEndpoint, "ApiExcludeEndpoint");
+function ApiExcludeController() {
+  return (target) => {
+    Reflect.defineMetadata(API_EXCLUDE_METADATA, true, target);
+  };
+}
+__name(ApiExcludeController, "ApiExcludeController");
+function isApiExcluded(target, propertyKey) {
+  if (Reflect.getMetadata(API_EXCLUDE_METADATA, target) === true) {
+    return true;
+  }
+  if (propertyKey !== void 0) {
+    return Reflect.getMetadata(API_EXCLUDE_METADATA, target.prototype, propertyKey) === true;
+  }
+  return false;
+}
+__name(isApiExcluded, "isApiExcluded");
+function ApiDeprecated(message) {
+  return (target, propertyKey, descriptor) => {
+    Reflect.defineMetadata(API_DEPRECATED_METADATA, {
+      deprecated: true,
+      message
+    }, target, propertyKey);
+    return descriptor;
+  };
+}
+__name(ApiDeprecated, "ApiDeprecated");
+function getApiDeprecated(target, propertyKey) {
+  return Reflect.getMetadata(API_DEPRECATED_METADATA, target.prototype, propertyKey);
+}
+__name(getApiDeprecated, "getApiDeprecated");
+
+// src/openapi/generator.ts
+import "reflect-metadata";
+import {
+  ParamType,
+  getControllerMetadata,
+  getRoutes,
+  getParamMetadata as getCoreParamMetadata,
+  getHttpCode,
+  getClassMetadata,
+  getMethodMetadata
+} from "@riktajs/core";
+
+// src/openapi/zod-to-openapi.ts
+import { z } from "zod";
+function isZodSchema(value) {
+  return value !== null && typeof value === "object" && ("_zod" in value || "_def" in value) && "safeParse" in value && typeof value.safeParse === "function";
+}
+__name(isZodSchema, "isZodSchema");
+function jsonSchemaToOpenApi(jsonSchema) {
+  if (typeof jsonSchema === "boolean") {
+    return jsonSchema ? {} : {
+      not: {}
+    };
+  }
+  const result = {};
+  const schema = jsonSchema;
+  if (Array.isArray(schema.type)) {
+    const types = schema.type;
+    const nullIndex = types.indexOf("null");
+    if (nullIndex !== -1) {
+      result.nullable = true;
+      const nonNullTypes = types.filter((t) => t !== "null");
+      if (nonNullTypes.length === 1) {
+        result.type = nonNullTypes[0];
+      } else if (nonNullTypes.length > 1) {
+        result.oneOf = nonNullTypes.map((t) => ({
+          type: t
+        }));
+      }
+    } else if (types.length === 1) {
+      result.type = types[0];
+    }
+  } else if (schema.type) {
+    result.type = schema.type;
+  }
+  const simpleProps = [
+    "format",
+    "description",
+    "default",
+    "example",
+    "enum",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minProperties",
+    "maxProperties",
+    "required",
+    "readOnly",
+    "writeOnly",
+    "deprecated"
+  ];
+  for (const prop of simpleProps) {
+    if (schema[prop] !== void 0) {
+      result[prop] = schema[prop];
+    }
+  }
+  if (schema.items) {
+    if (Array.isArray(schema.items)) {
+      result.items = {
+        oneOf: schema.items.map(jsonSchemaToOpenApi)
+      };
+    } else {
+      result.items = jsonSchemaToOpenApi(schema.items);
+    }
+  }
+  if (schema.properties) {
+    result.properties = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      result.properties[key] = jsonSchemaToOpenApi(value);
+    }
+  }
+  if (schema.additionalProperties !== void 0) {
+    if (typeof schema.additionalProperties === "boolean") {
+      result.additionalProperties = schema.additionalProperties;
+    } else {
+      result.additionalProperties = jsonSchemaToOpenApi(schema.additionalProperties);
+    }
+  }
+  if (schema.allOf) {
+    result.allOf = schema.allOf.map(jsonSchemaToOpenApi);
+  }
+  if (schema.oneOf) {
+    result.oneOf = schema.oneOf.map(jsonSchemaToOpenApi);
+  }
+  if (schema.anyOf) {
+    result.anyOf = schema.anyOf.map(jsonSchemaToOpenApi);
+  }
+  if (schema.not) {
+    result.not = jsonSchemaToOpenApi(schema.not);
+  }
+  if (schema.const !== void 0) {
+    result.enum = [
+      schema.const
+    ];
+  }
+  return result;
+}
+__name(jsonSchemaToOpenApi, "jsonSchemaToOpenApi");
+function zodToOpenApi(schema) {
+  const jsonSchema = z.toJSONSchema(schema, {
+    // Target OpenAPI 3.0 Schema Object format
+    target: "openapi-3.0",
+    // Allow unrepresentable types to be converted to {} instead of throwing
+    unrepresentable: "any",
+    // Custom override for types that need special handling
+    override: /* @__PURE__ */ __name((ctx) => {
+      const def = ctx.zodSchema._zod?.def;
+      if (!def) return;
+      if (def.type === "date") {
+        ctx.jsonSchema.type = "string";
+        ctx.jsonSchema.format = "date-time";
+      }
+      if (def.type === "bigint") {
+        ctx.jsonSchema.type = "integer";
+        ctx.jsonSchema.format = "int64";
+      }
+    }, "override")
+  });
+  return jsonSchemaToOpenApi(jsonSchema);
+}
+__name(zodToOpenApi, "zodToOpenApi");
+function toOpenApiSchema(schemaOrOpenApi) {
+  if (!schemaOrOpenApi) {
+    return void 0;
+  }
+  if (isZodSchema(schemaOrOpenApi)) {
+    return zodToOpenApi(schemaOrOpenApi);
+  }
+  return schemaOrOpenApi;
+}
+__name(toOpenApiSchema, "toOpenApiSchema");
+
+// src/openapi/generator.ts
+var DEFAULT_SWAGGER_CONFIG = {
+  info: {
+    title: "API Documentation",
+    version: "1.0.0"
+  }
+};
+var OpenApiGenerator = class {
+  static {
+    __name(this, "OpenApiGenerator");
+  }
+  config;
+  controllers = [];
+  globalSecuritySchemes = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    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",
+      description: config.description,
+      contact: config.contact,
+      license: config.license,
+      termsOfService: config.termsOfService
+    };
+    const { title, version, description, contact, license, termsOfService, ...restConfig } = config;
+    this.config = {
+      ...DEFAULT_SWAGGER_CONFIG,
+      ...restConfig,
+      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 = /* @__PURE__ */ new Set();
+    for (const controller of this.controllers) {
+      if (this.isControllerExcluded(controller)) {
+        continue;
+      }
+      const controllerMeta = this.getControllerMeta(controller);
+      if (!controllerMeta) continue;
+      const controllerTags = this.getControllerTags(controller);
+      const controllerDeprecated = this.isControllerDeprecated(controller);
+      for (const tag of controllerTags) {
+        if (!seenTags.has(tag)) {
+          seenTags.add(tag);
+          tags.push({
+            name: tag
+          });
+        }
+      }
+      const routes = this.getControllerRoutes(controller);
+      for (const route of routes) {
+        if (this.isEndpointExcluded(controller, route.handlerName)) {
+          continue;
+        }
+        const fullPath = this.normalizePath(controllerMeta.prefix, route.path);
+        const method = route.method.toLowerCase();
+        if (!paths[fullPath]) {
+          paths[fullPath] = {};
+        }
+        const operation = this.buildOperation(controller, route, controllerTags, controllerDeprecated);
+        paths[fullPath][method] = operation;
+      }
+    }
+    const securitySchemes = this.buildSecuritySchemes();
+    const document = {
+      openapi: "3.0.3",
+      info: this.config.info,
+      paths
+    };
+    if (tags.length > 0) {
+      document.tags = tags;
+    }
+    if (this.config.servers && this.config.servers.length > 0) {
+      document.servers = this.config.servers;
+    }
+    if (Object.keys(securitySchemes).length > 0) {
+      document.components = {
+        ...document.components,
+        securitySchemes
+      };
+    }
+    if (this.config.externalDocs) {
+      document.externalDocs = this.config.externalDocs;
+    }
+    return document;
+  }
+  // ============================================================================
+  // Private: Metadata Getters (using core helpers)
+  // ============================================================================
+  getControllerMeta(controller) {
+    return getControllerMetadata(controller);
+  }
+  getControllerRoutes(controller) {
+    return getRoutes(controller);
+  }
+  getControllerTags(controller) {
+    return getClassMetadata(API_TAGS_METADATA, controller) || [];
+  }
+  isControllerExcluded(controller) {
+    return getClassMetadata(API_EXCLUDE_METADATA, controller) === true;
+  }
+  isControllerDeprecated(controller) {
+    return getClassMetadata(API_DEPRECATED_METADATA, controller) === true;
+  }
+  isEndpointExcluded(controller, handlerName) {
+    return getMethodMetadata(API_EXCLUDE_METADATA, controller, handlerName) === true;
+  }
+  isEndpointDeprecated(controller, handlerName) {
+    const controllerLevel = getClassMetadata(API_DEPRECATED_METADATA, controller);
+    const methodLevel = getMethodMetadata(API_DEPRECATED_METADATA, controller, handlerName);
+    return controllerLevel?.deprecated === true || methodLevel?.deprecated === true;
+  }
+  getOperationMetadata(controller, handlerName) {
+    return getMethodMetadata(API_OPERATION_METADATA, controller, handlerName);
+  }
+  getResponseMetadata(controller, handlerName) {
+    return getMethodMetadata(API_RESPONSE_METADATA, controller, handlerName) || [];
+  }
+  getBodyMetadata(controller, handlerName) {
+    return getMethodMetadata(API_BODY_METADATA, controller, handlerName);
+  }
+  getSwaggerParamMetadata(controller, handlerName) {
+    return getMethodMetadata(API_PARAM_METADATA, controller, handlerName) || [];
+  }
+  getQueryMetadata(controller, handlerName) {
+    return getMethodMetadata(API_QUERY_METADATA, controller, handlerName) || [];
+  }
+  getHeaderMetadata(controller, handlerName) {
+    return getMethodMetadata(API_HEADER_METADATA, controller, handlerName) || [];
+  }
+  getSecurityMetadata(controller, handlerName) {
+    const controllerLevel = getClassMetadata(API_SECURITY_METADATA, controller);
+    const methodLevel = getMethodMetadata(API_SECURITY_METADATA, controller, handlerName);
+    const result = [];
+    if (controllerLevel && typeof controllerLevel === "object" && "name" in controllerLevel) {
+      result.push(controllerLevel);
+    } else if (Array.isArray(controllerLevel)) {
+      result.push(...controllerLevel);
+    }
+    if (methodLevel && typeof methodLevel === "object" && "name" in methodLevel) {
+      result.push(methodLevel);
+    } else if (Array.isArray(methodLevel)) {
+      result.push(...methodLevel);
+    }
+    return result;
+  }
+  getMethodTags(controller, handlerName) {
+    const operation = this.getOperationMetadata(controller, handlerName);
+    return operation?.tags;
+  }
+  getHttpStatusCode(controller, handlerName) {
+    return getHttpCode(controller, handlerName);
+  }
+  getCoreParams(controller, handlerName) {
+    return getCoreParamMetadata(controller, handlerName);
+  }
+  // ============================================================================
+  // Private: Path Utilities
+  // ============================================================================
+  normalizePath(prefix, path) {
+    let fullPath = "";
+    if (prefix) {
+      fullPath = prefix.startsWith("/") ? prefix : `/${prefix}`;
+    }
+    if (path) {
+      const cleanPath = path.startsWith("/") ? path : `/${path}`;
+      fullPath = fullPath + cleanPath;
+    }
+    if (!fullPath) {
+      fullPath = "/";
+    }
+    fullPath = fullPath.replace(/:([^/]+)/g, "{$1}");
+    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);
+    const methodTags = this.getMethodTags(controller, handlerName);
+    const operation = {
+      responses: {}
+    };
+    const tags = methodTags || controllerTags;
+    if (tags.length > 0) {
+      operation.tags = tags;
+    }
+    if (operationMeta?.summary) {
+      operation.summary = operationMeta.summary;
+    }
+    if (operationMeta?.description) {
+      operation.description = operationMeta.description;
+    }
+    if (operationMeta?.operationId) {
+      operation.operationId = operationMeta.operationId;
+    }
+    if (controllerDeprecated || operationMeta?.deprecated || this.isEndpointDeprecated(controller, handlerName)) {
+      operation.deprecated = true;
+    }
+    const parameters = this.buildParameters(controller, handlerName, route.path);
+    if (parameters.length > 0) {
+      operation.parameters = parameters;
+    }
+    if ([
+      "POST",
+      "PUT",
+      "PATCH"
+    ].includes(route.method)) {
+      const requestBody = this.buildRequestBody(controller, handlerName);
+      if (requestBody) {
+        operation.requestBody = requestBody;
+      }
+    }
+    operation.responses = this.buildResponses(controller, handlerName, route.statusCode);
+    const security = this.getSecurityMetadata(controller, handlerName);
+    if (security.length > 0) {
+      operation.security = security.map((s) => ({
+        [s.name]: s.scopes || []
+      }));
+    }
+    return operation;
+  }
+  buildParameters(controller, handlerName, routePath) {
+    const parameters = [];
+    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);
+    const usedPathParams = /* @__PURE__ */ new Set();
+    for (const param of paramDecorators) {
+      usedPathParams.add(param.name);
+      const baseSchema = toOpenApiSchema(param.schema);
+      const fallbackSchema = {
+        type: param.type || "string"
+      };
+      if (param.format) {
+        fallbackSchema.format = param.format;
+      }
+      parameters.push({
+        name: param.name,
+        in: "path",
+        required: true,
+        deprecated: param.deprecated,
+        description: param.description,
+        schema: baseSchema || fallbackSchema,
+        example: param.example
+      });
+    }
+    for (const paramName of pathParams) {
+      if (!usedPathParams.has(paramName)) {
+        const coreParam = coreParams.find((p) => p.type === ParamType.PARAM && p.key === paramName);
+        const schema = coreParam?.zodSchema ? zodToOpenApi(coreParam.zodSchema) : {
+          type: "string"
+        };
+        parameters.push({
+          name: paramName,
+          in: "path",
+          required: true,
+          schema
+        });
+      }
+    }
+    for (const query of queryDecorators) {
+      const baseSchema = toOpenApiSchema(query.schema);
+      const fallbackSchema = {
+        type: query.type || "string"
+      };
+      if (query.format) {
+        fallbackSchema.format = query.format;
+      }
+      parameters.push({
+        name: query.name,
+        in: "query",
+        required: query.required,
+        deprecated: query.deprecated,
+        description: query.description,
+        schema: baseSchema || fallbackSchema,
+        example: query.example
+      });
+    }
+    for (const header of headerDecorators) {
+      parameters.push({
+        name: header.name,
+        in: "header",
+        required: header.required,
+        deprecated: header.deprecated,
+        description: header.description,
+        schema: toOpenApiSchema(header.schema) || {
+          type: header.type || "string"
+        },
+        example: header.example
+      });
+    }
+    return parameters;
+  }
+  extractPathParams(path) {
+    const params = [];
+    const regex = /:([^/]+)|{([^}]+)}/g;
+    let match;
+    while ((match = regex.exec(path)) !== null) {
+      const paramName = match[1] ?? match[2];
+      if (paramName) {
+        params.push(paramName);
+      }
+    }
+    return params;
+  }
+  buildRequestBody(controller, handlerName) {
+    const bodyMeta = this.getBodyMetadata(controller, handlerName);
+    const coreParams = this.getCoreParams(controller, handlerName);
+    if (bodyMeta) {
+      const schema = toOpenApiSchema(bodyMeta.schema);
+      return {
+        description: bodyMeta.description,
+        required: bodyMeta.required ?? true,
+        content: {
+          [bodyMeta.type || "application/json"]: {
+            schema: bodyMeta.isArray && schema ? {
+              type: "array",
+              items: schema
+            } : schema,
+            example: bodyMeta.example
+          }
+        }
+      };
+    }
+    const bodyParam = coreParams.find((p) => p.type === ParamType.BODY);
+    if (bodyParam?.zodSchema) {
+      return {
+        required: true,
+        content: {
+          "application/json": {
+            schema: zodToOpenApi(bodyParam.zodSchema)
+          }
+        }
+      };
+    }
+    return void 0;
+  }
+  buildResponses(controller, handlerName, defaultStatusCode) {
+    const responses = {};
+    const responseMeta = this.getResponseMetadata(controller, handlerName);
+    const httpCode = this.getHttpStatusCode(controller, handlerName);
+    if (responseMeta.length > 0) {
+      for (const response of responseMeta) {
+        const statusCode = response.status.toString();
+        const schema = toOpenApiSchema(response.schema);
+        responses[statusCode] = {
+          description: response.description || this.getDefaultStatusDescription(response.status)
+        };
+        if (schema || response.example) {
+          responses[statusCode].content = {
+            [response.type || "application/json"]: {
+              schema: response.isArray && schema ? {
+                type: "array",
+                items: schema
+              } : schema,
+              example: response.example
+            }
+          };
+        }
+      }
+    } else {
+      const status = (httpCode || defaultStatusCode || 200).toString();
+      responses[status] = {
+        description: this.getDefaultStatusDescription(Number(status))
+      };
+    }
+    return responses;
+  }
+  getDefaultStatusDescription(status) {
+    const descriptions = {
+      200: "Successful response",
+      201: "Resource created successfully",
+      204: "No content",
+      400: "Bad request",
+      401: "Unauthorized",
+      403: "Forbidden",
+      404: "Not found",
+      409: "Conflict",
+      422: "Unprocessable entity",
+      500: "Internal server error"
+    };
+    return descriptions[status] || "Response";
+  }
+  buildSecuritySchemes() {
+    const schemes = {};
+    for (const [name, options] of this.globalSecuritySchemes) {
+      schemes[name] = {
+        type: options.type,
+        description: options.description
+      };
+      if (options.type === "apiKey") {
+        schemes[name].name = options.name;
+        schemes[name].in = options.in;
+      } else if (options.type === "http") {
+        schemes[name].scheme = options.scheme;
+        if (options.bearerFormat) {
+          schemes[name].bearerFormat = options.bearerFormat;
+        }
+      } else if (options.type === "oauth2" && options.flows) {
+        schemes[name].flows = options.flows;
+      }
+    }
+    return schemes;
+  }
+};
+
+// src/plugin/swagger.plugin.ts
+import fp from "fastify-plugin";
+import fastifySwagger from "@fastify/swagger";
+import fastifySwaggerUI from "@fastify/swagger-ui";
+import { registry } from "@riktajs/core";
+var DEFAULT_OPTIONS = {
+  jsonPath: "/docs/json",
+  uiPath: "/docs",
+  exposeUI: true,
+  exposeSpec: true
+};
+async function swaggerPluginImpl(fastify, options) {
+  const mergedOptions = {
+    ...DEFAULT_OPTIONS,
+    ...options
+  };
+  const { jsonPath, uiPath, exposeUI, exposeSpec, controllers, config, info, transform } = mergedOptions;
+  const apiInfo = info || config?.info || {
+    title: "API Documentation",
+    version: "1.0.0"
+  };
+  const generator = new OpenApiGenerator({
+    ...config,
+    info: apiInfo
+  });
+  const controllersToDocument = controllers || registry.getControllers();
+  for (const controller of controllersToDocument) {
+    generator.addController(controller);
+  }
+  if (config?.securitySchemes) {
+    for (const [name, scheme] of Object.entries(config.securitySchemes)) {
+      generator.addSecurityScheme(name, scheme);
+    }
+  }
+  let spec = generator.generate();
+  if (transform) {
+    spec = await transform(spec);
+  }
+  await fastify.register(fastifySwagger, {
+    mode: "static",
+    specification: {
+      document: spec
+    }
+  });
+  if (exposeUI) {
+    const uiOptions = {
+      routePrefix: uiPath,
+      uiConfig: {
+        docExpansion: "list",
+        deepLinking: true,
+        displayRequestDuration: true,
+        filter: true,
+        syntaxHighlight: {
+          activate: true,
+          theme: mergedOptions.theme === "dark" ? "monokai" : "agate"
+        }
+      },
+      staticCSP: true,
+      transformStaticCSP: /* @__PURE__ */ __name((header) => header, "transformStaticCSP")
+    };
+    if (mergedOptions.logo) {
+      uiOptions.logo = {
+        type: "image/png",
+        content: mergedOptions.logo.url,
+        href: mergedOptions.logo.url
+      };
+    }
+    await fastify.register(fastifySwaggerUI, uiOptions);
+  }
+  const defaultSwaggerUIJsonPath = `${uiPath}/json`;
+  const shouldRegisterCustomJsonRoute = exposeSpec && (!exposeUI || jsonPath !== defaultSwaggerUIJsonPath && jsonPath !== "/docs/json");
+  if (shouldRegisterCustomJsonRoute) {
+    fastify.get(jsonPath, {
+      schema: {
+        hide: true
+      }
+    }, async () => {
+      return spec;
+    });
+  }
+  fastify.decorate("openApiSpec", spec);
+}
+__name(swaggerPluginImpl, "swaggerPluginImpl");
+var swaggerPlugin = fp(swaggerPluginImpl, {
+  fastify: ">=4.0.0",
+  name: "@riktajs/swagger",
+  dependencies: []
+});
+async function registerSwagger(app, options = {}) {
+  await app.register(swaggerPlugin, options);
+}
+__name(registerSwagger, "registerSwagger");
+function createSwaggerConfig(options = {}) {
+  const mergedOptions = {
+    ...DEFAULT_OPTIONS,
+    ...options
+  };
+  const { uiPath, controllers, config, info } = mergedOptions;
+  const apiInfo = info || config?.info || {
+    title: "API Documentation",
+    version: "1.0.0"
+  };
+  const generator = new OpenApiGenerator({
+    ...config,
+    info: apiInfo
+  });
+  const controllersToDocument = controllers || registry.getControllers();
+  for (const controller of controllersToDocument) {
+    generator.addController(controller);
+  }
+  if (config?.securitySchemes) {
+    for (const [name, scheme] of Object.entries(config.securitySchemes)) {
+      generator.addSecurityScheme(name, scheme);
+    }
+  }
+  const specification = generator.generate();
+  return {
+    swaggerOptions: {
+      mode: "static",
+      specification: {
+        document: specification
+      }
+    },
+    swaggerUIOptions: {
+      routePrefix: uiPath,
+      uiConfig: {
+        docExpansion: "list",
+        deepLinking: true,
+        displayRequestDuration: true,
+        filter: true
+      }
+    },
+    specification
+  };
+}
+__name(createSwaggerConfig, "createSwaggerConfig");
+export {
+  API_BODY_METADATA,
+  API_DEPRECATED_METADATA,
+  API_EXCLUDE_METADATA,
+  API_HEADER_METADATA,
+  API_OPERATION_METADATA,
+  API_PARAM_METADATA,
+  API_PROPERTY_METADATA,
+  API_QUERY_METADATA,
+  API_RESPONSE_METADATA,
+  API_SECURITY_METADATA,
+  API_TAGS_METADATA,
+  ApiAcceptedResponse,
+  ApiBadRequestResponse,
+  ApiBasicAuth,
+  ApiBearerAuth,
+  ApiBody,
+  ApiConflictResponse,
+  ApiCookieAuth,
+  ApiCreatedResponse,
+  ApiDeprecated,
+  ApiExcludeController,
+  ApiExcludeEndpoint,
+  ApiForbiddenResponse,
+  ApiHeader,
+  ApiHideProperty,
+  ApiInternalServerErrorResponse,
+  ApiNoContentResponse,
+  ApiNotFoundResponse,
+  ApiOAuth2,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiProperty,
+  ApiPropertyOptional,
+  ApiQuery,
+  ApiResponse,
+  ApiSecurity,
+  ApiTags,
+  ApiUnauthorizedResponse,
+  ApiUnprocessableEntityResponse,
+  CONTROLLER_METADATA,
+  GUARDS_METADATA,
+  HTTP_CODE_METADATA,
+  OpenApiGenerator,
+  PARAM_METADATA,
+  ROUTES_METADATA,
+  ZOD_SCHEMA_METADATA,
+  createSwaggerConfig,
+  getApiBody,
+  getApiDeprecated,
+  getApiHeaders,
+  getApiOperation,
+  getApiParams,
+  getApiProperties,
+  getApiQueries,
+  getApiResponses,
+  getApiSecurity,
+  getApiTags,
+  isApiExcluded,
+  isZodSchema,
+  registerSwagger,
+  swaggerPlugin,
+  toOpenApiSchema,
+  zodToOpenApi
+};
+//# sourceMappingURL=index.js.map