@navios/openapi 0.7.0 → 0.9.1

package/lib/services-kEHEZqLZ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"services-kEHEZqLZ.cjs","names":["ApiTagToken","Symbol","for","ApiOperationToken","ApiSummaryToken","ApiDeprecatedToken","ApiSecurityToken","ApiExcludeToken","ApiStreamToken","Injectable","ApiDeprecatedToken","ApiExcludeToken","ApiOperationToken","ApiSecurityToken","ApiStreamToken","ApiSummaryToken","ApiTagToken","MetadataExtractorService","extract","controller","handler","controllerTag","customAttributes","get","handlerTag","operation","summary","deprecated","security","excluded","stream","tags","name","push","description","operationId","undefined","externalDocs","extractControllerMetadata","inject","Injectable","Logger","MetadataExtractorService","EndpointScannerService","logger","context","name","metadataExtractor","scan","modules","endpoints","moduleName","moduleMetadata","controllers","size","debug","controllerClass","controllerMeta","controllerEndpoints","scanController","push","length","module","handler","config","openApiMetadata","extract","excluded","classMethod","controller","Injectable","createSchema","SchemaConverterService","convert","schema","isFileSchema","type","format","transformFileProperties","properties","result","key","prop","Object","entries","description","items","inject","Injectable","MultipartAdapterToken","StreamAdapterToken","SchemaConverterService","PathBuilderService","schemaConverter","build","endpoint","config","handler","openApiMetadata","path","convertUrlParams","url","operation","tags","length","undefined","summary","description","operationId","deprecated","externalDocs","security","parameters","buildParameters","requestBody","buildRequestBody","responses","buildResponses","cleanOperation","Object","fromEntries","entries","filter","v","pathItem","method","toLowerCase","replace","extractUrlParamNames","matches","matchAll","Array","from","m","getEndpointType","adapterToken","params","urlParams","param","push","name","in","required","schema","type","querySchema","convert","schemaObj","properties","includes","buildMultipartRequestBody","buildJsonRequestBody","requestSchema","content","transformFileProperties","buildStreamResponses","buildJsonResponses","successCode","successStatusCode","toString","responseSchema","contentType","stream","getStreamContent","format","inject","Injectable","Logger","EndpointScannerService","PathBuilderService","OpenApiGeneratorService","logger","context","name","scanner","pathBuilder","generate","modules","options","debug","endpoints","scan","paths","buildPaths","discoveredTags","collectTags","tags","mergeTags","document","openapi","info","servers","length","externalDocs","security","securitySchemes","components","Object","keys","endpoint","path","pathItem","build","Set","tag","openApiMetadata","add","configuredTags","tagMap","Map","set","tagName","has","Array","from","values"],"sources":["../src/tokens/index.mts","../src/services/metadata-extractor.service.mts","../src/services/endpoint-scanner.service.mts","../src/services/schema-converter.service.mts","../src/services/path-builder.service.mts","../src/services/openapi-generator.service.mts"],"sourcesContent":["/**\n * Tokens for OpenAPI metadata attributes\n */\n\n/** Token for @ApiTag decorator */\nexport const ApiTagToken = Symbol.for('navios:openapi:tag')\n\n/** Token for @ApiOperation decorator */\nexport const ApiOperationToken = Symbol.for('navios:openapi:operation')\n\n/** Token for @ApiSummary decorator */\nexport const ApiSummaryToken = Symbol.for('navios:openapi:summary')\n\n/** Token for @ApiDeprecated decorator */\nexport const ApiDeprecatedToken = Symbol.for('navios:openapi:deprecated')\n\n/** Token for @ApiSecurity decorator */\nexport const ApiSecurityToken = Symbol.for('navios:openapi:security')\n\n/** Token for @ApiExclude decorator */\nexport const ApiExcludeToken = Symbol.for('navios:openapi:exclude')\n\n/** Token for @ApiStream decorator */\nexport const ApiStreamToken = Symbol.for('navios:openapi:stream')\n","import type { ControllerMetadata, HandlerMetadata } from '@navios/core'\n\nimport { Injectable } from '@navios/core'\n\nimport type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.mjs'\n\nimport {\n  ApiDeprecatedToken,\n  ApiExcludeToken,\n  ApiOperationToken,\n  ApiSecurityToken,\n  ApiStreamToken,\n  ApiSummaryToken,\n  ApiTagToken,\n} from '../tokens/index.mjs'\n\n/**\n * Service responsible for extracting OpenAPI metadata from decorators.\n *\n * Merges controller-level and handler-level metadata to produce\n * a complete OpenAPI metadata object for each endpoint.\n */\n@Injectable()\nexport class MetadataExtractorService {\n  /**\n   * Extracts and merges OpenAPI metadata from controller and handler.\n   *\n   * @param controller - Controller metadata\n   * @param handler - Handler metadata\n   * @returns Merged OpenAPI metadata\n   */\n  extract(\n    controller: ControllerMetadata,\n    handler: HandlerMetadata<any>,\n  ): OpenApiEndpointMetadata {\n    // Extract controller-level metadata\n    const controllerTag = controller.customAttributes.get(ApiTagToken) as\n      | { name: string; description?: string }\n      | undefined\n\n    // Extract handler-level metadata\n    const handlerTag = handler.customAttributes.get(ApiTagToken) as\n      | { name: string; description?: string }\n      | undefined\n    const operation = handler.customAttributes.get(ApiOperationToken) as\n      | {\n          summary?: string\n          description?: string\n          operationId?: string\n          deprecated?: boolean\n          externalDocs?: { url: string; description?: string }\n        }\n      | undefined\n    const summary = handler.customAttributes.get(ApiSummaryToken) as\n      | string\n      | undefined\n    const deprecated = handler.customAttributes.get(ApiDeprecatedToken) as\n      | { message?: string }\n      | undefined\n    const security = handler.customAttributes.get(ApiSecurityToken) as\n      | Record<string, string[]>\n      | undefined\n    const excluded = handler.customAttributes.get(ApiExcludeToken) as\n      | boolean\n      | undefined\n    const stream = handler.customAttributes.get(ApiStreamToken) as\n      | { contentType: string; description?: string }\n      | undefined\n\n    // Build tags array (handler tag takes precedence but both are included)\n    const tags: string[] = []\n    if (controllerTag?.name) {\n      tags.push(controllerTag.name)\n    }\n    if (handlerTag?.name && handlerTag.name !== controllerTag?.name) {\n      tags.push(handlerTag.name)\n    }\n\n    return {\n      tags,\n      summary: operation?.summary ?? summary,\n      description: operation?.description,\n      operationId: operation?.operationId,\n      deprecated: deprecated !== undefined || operation?.deprecated === true,\n      externalDocs: operation?.externalDocs,\n      security: security ? [security] : undefined,\n      excluded: excluded === true,\n      stream,\n    }\n  }\n}\n","import type {\n  ControllerMetadata,\n  HandlerMetadata,\n  ModuleMetadata,\n} from '@navios/core'\nimport type { BaseEndpointConfig } from '@navios/builder'\n\nimport { extractControllerMetadata, inject, Injectable, Logger } from '@navios/core'\n\nimport type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.mjs'\n\nimport { MetadataExtractorService } from './metadata-extractor.service.mjs'\n\n/**\n * Represents a discovered endpoint with all its metadata\n */\nexport interface DiscoveredEndpoint {\n  /** Module metadata */\n  module: ModuleMetadata\n  /** Controller class */\n  controllerClass: any\n  /** Controller metadata */\n  controller: ControllerMetadata\n  /** Handler (endpoint) metadata */\n  handler: HandlerMetadata<any>\n  /** Endpoint configuration from @navios/builder */\n  config: BaseEndpointConfig\n  /** Extracted OpenAPI metadata */\n  openApiMetadata: OpenApiEndpointMetadata\n}\n\n/**\n * Service responsible for scanning modules and discovering endpoints.\n *\n * Iterates through all modules, controllers, and endpoints,\n * extracting OpenAPI metadata from decorators.\n */\n@Injectable()\nexport class EndpointScannerService {\n  private readonly logger = inject(Logger, {\n    context: EndpointScannerService.name,\n  })\n\n  private readonly metadataExtractor = inject(MetadataExtractorService)\n\n  /**\n   * Scans all loaded modules and discovers endpoints.\n   *\n   * @param modules - Map of loaded modules from NaviosApplication\n   * @returns Array of discovered endpoints\n   */\n  scan(modules: Map<string, ModuleMetadata>): DiscoveredEndpoint[] {\n    const endpoints: DiscoveredEndpoint[] = []\n\n    for (const [moduleName, moduleMetadata] of modules) {\n      if (!moduleMetadata.controllers || moduleMetadata.controllers.size === 0) {\n        continue\n      }\n\n      this.logger.debug(`Scanning module: ${moduleName}`)\n\n      for (const controllerClass of moduleMetadata.controllers) {\n        const controllerMeta = extractControllerMetadata(controllerClass)\n        const controllerEndpoints = this.scanController(\n          moduleMetadata,\n          controllerClass,\n          controllerMeta,\n        )\n        endpoints.push(...controllerEndpoints)\n      }\n    }\n\n    this.logger.debug(`Discovered ${endpoints.length} endpoints`)\n    return endpoints\n  }\n\n  /**\n   * Scans a controller and returns its endpoints\n   */\n  private scanController(\n    module: ModuleMetadata,\n    controllerClass: any,\n    controllerMeta: ControllerMetadata,\n  ): DiscoveredEndpoint[] {\n    const endpoints: DiscoveredEndpoint[] = []\n\n    for (const handler of controllerMeta.endpoints) {\n      // Skip endpoints without config (non-builder endpoints)\n      if (!handler.config) {\n        continue\n      }\n\n      const openApiMetadata = this.metadataExtractor.extract(\n        controllerMeta,\n        handler,\n      )\n\n      // Skip excluded endpoints\n      if (openApiMetadata.excluded) {\n        this.logger.debug(\n          `Skipping excluded endpoint: ${handler.classMethod}`,\n        )\n        continue\n      }\n\n      endpoints.push({\n        module,\n        controllerClass,\n        controller: controllerMeta,\n        handler,\n        config: handler.config as BaseEndpointConfig,\n        openApiMetadata,\n      })\n    }\n\n    return endpoints\n  }\n}\n","import type { ZodType } from 'zod/v4'\nimport type { oas31 } from 'zod-openapi'\n\nimport { Injectable } from '@navios/core'\nimport { createSchema } from 'zod-openapi'\n\ntype SchemaObject = oas31.SchemaObject\ntype ReferenceObject = oas31.ReferenceObject\n\n/**\n * Result of schema conversion\n */\nexport interface SchemaConversionResult {\n  schema: SchemaObject | ReferenceObject\n  components: Record<string, SchemaObject>\n}\n\n/**\n * Service responsible for converting Zod schemas to OpenAPI schemas.\n *\n * Uses zod-openapi library which supports Zod 4's native `.meta()` method\n * for OpenAPI-specific metadata.\n */\n@Injectable()\nexport class SchemaConverterService {\n  /**\n   * Converts a Zod schema to an OpenAPI schema object.\n   *\n   * @param schema - Zod schema to convert\n   * @returns OpenAPI schema object with any component schemas\n   *\n   * @example\n   * ```typescript\n   * const userSchema = z.object({\n   *   id: z.string().meta({ openapi: { example: 'usr_123' } }),\n   *   name: z.string(),\n   * })\n   *\n   * const result = schemaConverter.convert(userSchema)\n   * // { schema: { type: 'object', properties: { ... } }, components: {} }\n   * ```\n   */\n  convert(schema: ZodType): SchemaConversionResult {\n    return createSchema(schema)\n  }\n\n  /**\n   * Checks if a schema property represents a File type.\n   *\n   * Used for multipart form handling to convert File types to binary format.\n   *\n   * @param schema - Schema object to check\n   * @returns true if the schema represents a file\n   */\n  isFileSchema(schema: SchemaObject): boolean {\n    return schema.type === 'string' && schema.format === 'binary'\n  }\n\n  /**\n   * Transforms schema properties to handle File/Blob types for multipart.\n   *\n   * Converts File types to OpenAPI binary format and handles arrays of files.\n   *\n   * @param properties - Schema properties object\n   * @returns Transformed properties with file types as binary\n   */\n  transformFileProperties(\n    properties: Record<string, SchemaObject>,\n  ): Record<string, SchemaObject> {\n    const result: Record<string, SchemaObject> = {}\n\n    for (const [key, prop] of Object.entries(properties)) {\n      if (this.isFileSchema(prop)) {\n        result[key] = {\n          type: 'string',\n          format: 'binary',\n          description: prop.description,\n        }\n      } else if (\n        prop.type === 'array' &&\n        prop.items &&\n        this.isFileSchema(prop.items as SchemaObject)\n      ) {\n        result[key] = {\n          type: 'array',\n          items: { type: 'string', format: 'binary' },\n          description: prop.description,\n        }\n      } else {\n        result[key] = prop\n      }\n    }\n\n    return result\n  }\n}\n","import type { BaseEndpointConfig } from '@navios/builder'\nimport type { HandlerMetadata } from '@navios/core'\nimport type { oas31 } from 'zod-openapi'\n\nimport {\n  EndpointAdapterToken,\n  inject,\n  Injectable,\n  MultipartAdapterToken,\n  StreamAdapterToken,\n} from '@navios/core'\n\nimport type { DiscoveredEndpoint } from './endpoint-scanner.service.mjs'\n\nimport { SchemaConverterService } from './schema-converter.service.mjs'\n\ntype ContentObject = oas31.ContentObject\ntype OperationObject = oas31.OperationObject\ntype ParameterObject = oas31.ParameterObject\ntype PathItemObject = oas31.PathItemObject\ntype RequestBodyObject = oas31.RequestBodyObject\ntype ResponsesObject = oas31.ResponsesObject\ntype SchemaObject = oas31.SchemaObject\n\n/**\n * Result of path item generation\n */\nexport interface PathItemResult {\n  path: string\n  pathItem: PathItemObject\n}\n\n/**\n * Service responsible for building OpenAPI path items from endpoints.\n *\n * Handles URL parameter conversion, request body generation,\n * and response schema generation for different endpoint types.\n */\n@Injectable()\nexport class PathBuilderService {\n  private readonly schemaConverter = inject(SchemaConverterService)\n\n  /**\n   * Generates an OpenAPI path item for a discovered endpoint.\n   *\n   * @param endpoint - Discovered endpoint with metadata\n   * @returns Path string and path item object\n   */\n  build(endpoint: DiscoveredEndpoint): PathItemResult {\n    const { config, handler, openApiMetadata } = endpoint\n\n    // Convert $param to {param} format for OpenAPI\n    const path = this.convertUrlParams(config.url)\n\n    const operation: OperationObject = {\n      tags: openApiMetadata.tags.length > 0 ? openApiMetadata.tags : undefined,\n      summary: openApiMetadata.summary,\n      description: openApiMetadata.description,\n      operationId: openApiMetadata.operationId,\n      deprecated: openApiMetadata.deprecated || undefined,\n      externalDocs: openApiMetadata.externalDocs,\n      security: openApiMetadata.security,\n      parameters: this.buildParameters(config),\n      requestBody: this.buildRequestBody(config, handler),\n      responses: this.buildResponses(endpoint),\n    }\n\n    // Remove undefined properties\n    const cleanOperation = Object.fromEntries(\n      Object.entries(operation).filter(([, v]) => v !== undefined),\n    ) as OperationObject\n\n    return {\n      path,\n      pathItem: {\n        [config.method.toLowerCase()]: cleanOperation,\n      },\n    }\n  }\n\n  /**\n   * Converts Navios URL param format ($param) to OpenAPI format ({param})\n   */\n  convertUrlParams(url: string): string {\n    return url.replace(/\\$(\\w+)/g, '{$1}')\n  }\n\n  /**\n   * Extracts URL parameter names from a URL pattern\n   */\n  extractUrlParamNames(url: string): string[] {\n    const matches = url.matchAll(/\\$(\\w+)/g)\n    return Array.from(matches, (m) => m[1])\n  }\n\n  /**\n   * Gets the endpoint type based on the adapter token\n   */\n  getEndpointType(\n    handler: HandlerMetadata<any>,\n  ): 'endpoint' | 'multipart' | 'stream' {\n    if (handler.adapterToken === MultipartAdapterToken) {\n      return 'multipart'\n    }\n    if (handler.adapterToken === StreamAdapterToken) {\n      return 'stream'\n    }\n    return 'endpoint'\n  }\n\n  /**\n   * Builds OpenAPI parameters from endpoint config\n   */\n  private buildParameters(config: BaseEndpointConfig): ParameterObject[] {\n    const params: ParameterObject[] = []\n\n    // URL parameters (from $paramName in URL)\n    const urlParams = this.extractUrlParamNames(config.url)\n    for (const param of urlParams) {\n      params.push({\n        name: param,\n        in: 'path',\n        required: true,\n        schema: { type: 'string' },\n      })\n    }\n\n    // Query parameters (from querySchema)\n    if (config.querySchema) {\n      const { schema: querySchema } = this.schemaConverter.convert(\n        config.querySchema,\n      )\n      const schemaObj = querySchema as SchemaObject\n      if (schemaObj.properties) {\n        for (const [name, schema] of Object.entries(schemaObj.properties)) {\n          params.push({\n            name,\n            in: 'query',\n            required: schemaObj.required?.includes(name) ?? false,\n            schema: schema as SchemaObject,\n            description: (schema as SchemaObject).description,\n          })\n        }\n      }\n    }\n\n    return params\n  }\n\n  /**\n   * Builds request body based on endpoint type\n   */\n  private buildRequestBody(\n    config: BaseEndpointConfig,\n    handler: HandlerMetadata<any>,\n  ): RequestBodyObject | undefined {\n    const type = this.getEndpointType(handler)\n\n    switch (type) {\n      case 'multipart':\n        return this.buildMultipartRequestBody(config)\n      case 'stream':\n        return undefined // Streams typically don't have request bodies\n      case 'endpoint':\n      default:\n        return this.buildJsonRequestBody(config)\n    }\n  }\n\n  /**\n   * Builds request body for JSON endpoints\n   */\n  private buildJsonRequestBody(\n    config: BaseEndpointConfig,\n  ): RequestBodyObject | undefined {\n    if (!config.requestSchema) {\n      return undefined\n    }\n\n    const { schema } = this.schemaConverter.convert(config.requestSchema)\n\n    return {\n      required: true,\n      content: {\n        'application/json': {\n          schema,\n        },\n      },\n    }\n  }\n\n  /**\n   * Builds request body for multipart endpoints\n   */\n  private buildMultipartRequestBody(\n    config: BaseEndpointConfig,\n  ): RequestBodyObject {\n    if (!config.requestSchema) {\n      return {\n        required: true,\n        content: {\n          'multipart/form-data': {\n            schema: { type: 'object' },\n          },\n        },\n      }\n    }\n\n    const schema = this.schemaConverter.convert(config.requestSchema).schema as SchemaObject\n\n    // Transform schema properties to handle File types\n    const properties = this.schemaConverter.transformFileProperties(\n      (schema.properties as Record<string, SchemaObject>) || {},\n    )\n\n    return {\n      required: true,\n      content: {\n        'multipart/form-data': {\n          schema: {\n            type: 'object',\n            properties,\n            required: schema.required,\n          },\n        },\n      },\n    }\n  }\n\n  /**\n   * Builds responses based on endpoint type\n   */\n  private buildResponses(endpoint: DiscoveredEndpoint): ResponsesObject {\n    const { config, handler } = endpoint\n    const type = this.getEndpointType(handler)\n\n    switch (type) {\n      case 'stream':\n        return this.buildStreamResponses(endpoint)\n      case 'multipart':\n      case 'endpoint':\n      default:\n        return this.buildJsonResponses(config, handler)\n    }\n  }\n\n  /**\n   * Builds responses for JSON endpoints\n   */\n  private buildJsonResponses(\n    config: BaseEndpointConfig,\n    handler: HandlerMetadata<any>,\n  ): ResponsesObject {\n    const successCode = handler.successStatusCode?.toString() ?? '200'\n\n    if (!config.responseSchema) {\n      return {\n        [successCode]: {\n          description: 'Successful response',\n        },\n      }\n    }\n\n    const { schema } = this.schemaConverter.convert(config.responseSchema)\n\n    return {\n      [successCode]: {\n        description: 'Successful response',\n        content: {\n          'application/json': {\n            schema,\n          },\n        },\n      },\n    }\n  }\n\n  /**\n   * Builds responses for stream endpoints\n   */\n  private buildStreamResponses(endpoint: DiscoveredEndpoint): ResponsesObject {\n    const { openApiMetadata, handler } = endpoint\n    const successCode = handler.successStatusCode?.toString() ?? '200'\n\n    const contentType =\n      openApiMetadata.stream?.contentType ?? 'application/octet-stream'\n    const description =\n      openApiMetadata.stream?.description ?? 'Stream response'\n\n    const content: ContentObject = this.getStreamContent(contentType)\n\n    return {\n      [successCode]: {\n        description,\n        content,\n      },\n    }\n  }\n\n  /**\n   * Gets content object for different stream types\n   */\n  private getStreamContent(contentType: string): ContentObject {\n    switch (contentType) {\n      case 'text/event-stream':\n        return {\n          'text/event-stream': {\n            schema: {\n              type: 'string',\n              description: 'Server-Sent Events stream',\n            },\n          },\n        }\n\n      case 'application/octet-stream':\n        return {\n          'application/octet-stream': {\n            schema: {\n              type: 'string',\n              format: 'binary',\n              description: 'Binary file download',\n            },\n          },\n        }\n\n      case 'application/json':\n        return {\n          'application/json': {\n            schema: {\n              type: 'string',\n              description: 'Newline-delimited JSON stream',\n            },\n          },\n        }\n\n      default:\n        return {\n          [contentType]: {\n            schema: { type: 'string', format: 'binary' },\n          },\n        }\n    }\n  }\n}\n","import type { ModuleMetadata } from '@navios/core'\nimport type { oas31 } from 'zod-openapi'\n\nimport { inject, Injectable, Logger } from '@navios/core'\n\nimport type { DiscoveredEndpoint } from './endpoint-scanner.service.mjs'\n\nimport { EndpointScannerService } from './endpoint-scanner.service.mjs'\nimport { PathBuilderService } from './path-builder.service.mjs'\n\ntype OpenAPIObject = oas31.OpenAPIObject\ntype PathsObject = oas31.PathsObject\ntype SecuritySchemeObject = oas31.SecuritySchemeObject\ntype TagObject = oas31.TagObject\n\n/**\n * Options for generating the OpenAPI document\n */\nexport interface OpenApiGeneratorOptions {\n  /**\n   * OpenAPI document info\n   */\n  info: {\n    title: string\n    version: string\n    description?: string\n    termsOfService?: string\n    contact?: {\n      name?: string\n      url?: string\n      email?: string\n    }\n    license?: {\n      name: string\n      url?: string\n    }\n  }\n\n  /**\n   * External documentation\n   */\n  externalDocs?: {\n    url: string\n    description?: string\n  }\n\n  /**\n   * Server definitions\n   */\n  servers?: Array<{\n    url: string\n    description?: string\n    variables?: Record<\n      string,\n      {\n        default: string\n        enum?: string[]\n        description?: string\n      }\n    >\n  }>\n\n  /**\n   * Security scheme definitions\n   */\n  securitySchemes?: Record<string, SecuritySchemeObject>\n\n  /**\n   * Global security requirements\n   */\n  security?: Array<Record<string, string[]>>\n\n  /**\n   * Tag definitions with descriptions\n   */\n  tags?: TagObject[]\n}\n\n/**\n * Service responsible for generating the complete OpenAPI document.\n *\n * Orchestrates endpoint discovery, path generation, and document assembly.\n */\n@Injectable()\nexport class OpenApiGeneratorService {\n  private readonly logger = inject(Logger, {\n    context: OpenApiGeneratorService.name,\n  })\n\n  private readonly scanner = inject(EndpointScannerService)\n  private readonly pathBuilder = inject(PathBuilderService)\n\n  /**\n   * Generates an OpenAPI document from loaded modules.\n   *\n   * @param modules - Map of loaded modules\n   * @param options - OpenAPI generation options\n   * @returns Complete OpenAPI document\n   */\n  generate(\n    modules: Map<string, ModuleMetadata>,\n    options: OpenApiGeneratorOptions,\n  ): OpenAPIObject {\n    this.logger.debug('Generating OpenAPI document')\n\n    // Discover all endpoints\n    const endpoints = this.scanner.scan(modules)\n\n    // Generate paths\n    const paths = this.buildPaths(endpoints)\n\n    // Collect unique tags from endpoints\n    const discoveredTags = this.collectTags(endpoints)\n\n    // Merge discovered tags with configured tags\n    const tags = this.mergeTags(discoveredTags, options.tags)\n\n    // Build the OpenAPI document\n    const document: OpenAPIObject = {\n      openapi: '3.1.0',\n      info: options.info,\n      paths,\n    }\n\n    // Add optional fields\n    if (options.servers && options.servers.length > 0) {\n      document.servers = options.servers\n    }\n\n    if (options.externalDocs) {\n      document.externalDocs = options.externalDocs\n    }\n\n    if (tags.length > 0) {\n      document.tags = tags\n    }\n\n    if (options.security) {\n      document.security = options.security\n    }\n\n    if (options.securitySchemes) {\n      document.components = {\n        ...document.components,\n        securitySchemes: options.securitySchemes,\n      }\n    }\n\n    this.logger.debug(\n      `Generated OpenAPI document with ${Object.keys(paths).length} paths`,\n    )\n\n    return document\n  }\n\n  /**\n   * Builds paths object from discovered endpoints\n   */\n  private buildPaths(endpoints: DiscoveredEndpoint[]): PathsObject {\n    const paths: PathsObject = {}\n\n    for (const endpoint of endpoints) {\n      const { path, pathItem } = this.pathBuilder.build(endpoint)\n\n      // Merge with existing path if methods differ\n      if (paths[path]) {\n        paths[path] = {\n          ...paths[path],\n          ...pathItem,\n        }\n      } else {\n        paths[path] = pathItem\n      }\n    }\n\n    return paths\n  }\n\n  /**\n   * Collects unique tags from endpoints\n   */\n  private collectTags(endpoints: DiscoveredEndpoint[]): Set<string> {\n    const tags = new Set<string>()\n\n    for (const endpoint of endpoints) {\n      for (const tag of endpoint.openApiMetadata.tags) {\n        tags.add(tag)\n      }\n    }\n\n    return tags\n  }\n\n  /**\n   * Merges discovered tags with configured tags\n   */\n  private mergeTags(\n    discoveredTags: Set<string>,\n    configuredTags?: TagObject[],\n  ): TagObject[] {\n    const tagMap = new Map<string, TagObject>()\n\n    // Add configured tags first (they have descriptions)\n    if (configuredTags) {\n      for (const tag of configuredTags) {\n        tagMap.set(tag.name, tag)\n      }\n    }\n\n    // Add discovered tags that aren't already configured\n    for (const tagName of discoveredTags) {\n      if (!tagMap.has(tagName)) {\n        tagMap.set(tagName, { name: tagName })\n      }\n    }\n\n    return Array.from(tagMap.values())\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navios/openapi",
-  "version": "0.7.0",
+  "version": "0.9.1",
   "author": {
     "name": "Oleksandr Hanzha",
     "email": "alex@granted.name"
@@ -12,7 +12,7 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@navios/core": "^0.7.1",
+    "@navios/core": "^0.9.3",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "typings": "./lib/index.d.mts",
@@ -28,16 +28,26 @@
         "types": "./lib/index.d.cts",
         "default": "./lib/index.cjs"
       }
+    },
+    "./legacy-compat": {
+      "import": {
+        "types": "./lib/legacy-compat/index.d.mts",
+        "default": "./lib/legacy-compat/index.mjs"
+      },
+      "require": {
+        "types": "./lib/legacy-compat/index.d.cts",
+        "default": "./lib/legacy-compat/index.cjs"
+      }
     }
   },
   "devDependencies": {
-    "@navios/builder": "^0.5.1",
-    "@navios/core": "^0.7.1",
+    "@navios/builder": "^0.5.3",
+    "@navios/core": "^0.9.3",
     "typescript": "^5.9.3",
     "zod": "^4.2.1"
   },
   "dependencies": {
-    "@navios/di": "^0.6.1",
+    "@navios/di": "^0.9.2",
     "yaml": "^2.8.2",
     "zod-openapi": "^5.4.5"
   }

package/src/__tests__/metadata.spec.mts

@@ -1,11 +1,9 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { HandlerMetadata } from '@navios/core'
 
-import {
-  Controller,
-  extractControllerMetadata,
-  type HandlerMetadata,
-} from '@navios/core'
-import { TestContainer } from '@navios/di'
+import { Controller, extractControllerMetadata } from '@navios/core'
+import { TestContainer } from '@navios/di/testing'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
 import {
   ApiDeprecated,

package/src/__tests__/services.spec.mts

@@ -1,10 +1,10 @@
+import { TestContainer } from '@navios/di/testing'
+
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { z } from 'zod/v4'
 
-import { TestContainer } from '@navios/di'
-
-import { SchemaConverterService } from '../services/schema-converter.service.mjs'
 import { PathBuilderService } from '../services/path-builder.service.mjs'
+import { SchemaConverterService } from '../services/schema-converter.service.mjs'
 
 describe('OpenAPI Services', () => {
   let container: TestContainer
@@ -202,10 +202,9 @@ describe('OpenAPI Services', () => {
 
     it('should extract multiple params', async () => {
       const service = await container.get(PathBuilderService)
-      expect(service.extractUrlParamNames('/users/$userId/posts/$postId')).toEqual([
-        'userId',
-        'postId',
-      ])
+      expect(
+        service.extractUrlParamNames('/users/$userId/posts/$postId'),
+      ).toEqual(['userId', 'postId'])
     })
 
     it('should return empty array for no params', async () => {

package/src/legacy-compat/__type-tests__/legacy-decorators.spec-d.mts

@@ -0,0 +1,347 @@
+// oxlint-disable no-unused-vars
+import type { EndpointParams, EndpointResult } from '@navios/core/legacy-compat'
+
+import { builder } from '@navios/builder'
+import { Controller, Endpoint } from '@navios/core/legacy-compat'
+
+import { describe, expectTypeOf, test } from 'vitest'
+import { z } from 'zod/v4'
+
+import {
+  ApiDeprecated,
+  ApiExclude,
+  ApiOperation,
+  ApiSecurity,
+  ApiStream,
+  ApiSummary,
+  ApiTag,
+} from '../index.mjs'
+
+// Create a test API builder
+const api = builder()
+
+// Test schemas
+const responseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+const querySchema = z.object({
+  page: z.number(),
+  limit: z.number(),
+})
+
+// Test endpoint declarations
+const getUserEndpoint = api.declareEndpoint({
+  method: 'GET',
+  url: '/users/$userId',
+  querySchema,
+  responseSchema,
+})
+
+const createUserEndpoint = api.declareEndpoint({
+  method: 'POST',
+  url: '/users',
+  requestSchema: z.object({
+    name: z.string(),
+    email: z.string(),
+  }),
+  responseSchema,
+})
+
+const downloadFileEndpoint = api.declareStream({
+  method: 'GET',
+  url: '/files/$fileId',
+  querySchema,
+})
+
+describe('Legacy OpenAPI Decorators Type Safety', () => {
+  describe('ApiTag decorator', () => {
+    test('should work on controller level', () => {
+      @ApiTag('Users', 'User management operations')
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work on method level', () => {
+      @Controller()
+      class UserController {
+        @ApiTag('Users')
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should accept optional description', () => {
+      @ApiTag('Users')
+      @Controller()
+      class UserController {}
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiOperation decorator', () => {
+    test('should work with full options', () => {
+      @Controller()
+      class UserController {
+        @ApiOperation({
+          summary: 'Get user by ID',
+          description: 'Retrieves a user by their unique identifier',
+          operationId: 'getUserById',
+          deprecated: false,
+          externalDocs: {
+            url: 'https://docs.example.com',
+            description: 'API docs',
+          },
+        })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with partial options', () => {
+      @Controller()
+      class UserController {
+        @ApiOperation({
+          summary: 'Get user',
+        })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiSummary decorator', () => {
+    test('should work with string summary', () => {
+      @Controller()
+      class UserController {
+        @ApiSummary('Get user by ID')
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiDeprecated decorator', () => {
+    test('should work without message', () => {
+      @Controller()
+      class UserController {
+        @ApiDeprecated()
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with deprecation message', () => {
+      @Controller()
+      class UserController {
+        @ApiDeprecated('Use GET /v2/users/:id instead')
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiSecurity decorator', () => {
+    test('should work with bearer auth', () => {
+      @Controller()
+      class UserController {
+        @ApiSecurity({ bearerAuth: [] })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with OAuth2 scopes', () => {
+      @Controller()
+      class UserController {
+        @ApiSecurity({ oauth2: ['users:read', 'users:write'] })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with multiple auth methods', () => {
+      @Controller()
+      class UserController {
+        @ApiSecurity({ bearerAuth: [], apiKey: [] })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiExclude decorator', () => {
+    test('should work on endpoint', () => {
+      @Controller()
+      class HealthController {
+        @ApiExclude()
+        @Endpoint(getUserEndpoint)
+        async healthCheck(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: 'health', name: 'ok' }
+        }
+      }
+
+      expectTypeOf(HealthController).toBeConstructibleWith()
+    })
+  })
+
+  describe('ApiStream decorator', () => {
+    test('should work with content type and description', () => {
+      @Controller()
+      class FileController {
+        @ApiStream({
+          contentType: 'application/octet-stream',
+          description: 'Download file as binary stream',
+        })
+        @Endpoint(getUserEndpoint)
+        async downloadFile(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'file.bin' }
+        }
+      }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
+    })
+
+    test('should work for SSE endpoints', () => {
+      @Controller()
+      class EventController {
+        @ApiStream({
+          contentType: 'text/event-stream',
+          description: 'Real-time event stream',
+        })
+        @Endpoint(getUserEndpoint)
+        async streamEvents(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: 'stream', name: 'events' }
+        }
+      }
+
+      expectTypeOf(EventController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Integration - multiple decorators together', () => {
+    test('should work with all OpenAPI decorators on controller and methods', () => {
+      @ApiTag('Users', 'User management API')
+      @Controller()
+      class UserController {
+        @ApiOperation({
+          summary: 'Get user by ID',
+          description: 'Retrieves a user by their unique identifier',
+          operationId: 'getUserById',
+        })
+        @ApiSecurity({ bearerAuth: [] })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return {
+            id: request.urlParams.userId.toString(),
+            name: 'John',
+          }
+        }
+
+        @ApiSummary('Create a new user')
+        @ApiSecurity({ bearerAuth: [] })
+        @Endpoint(createUserEndpoint)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          return {
+            id: '1',
+            name: request.data.name,
+          }
+        }
+
+        @ApiDeprecated('Use GET /v2/users/:id instead')
+        @ApiTag('Legacy')
+        @Endpoint(getUserEndpoint)
+        async getLegacyUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+
+        @ApiExclude()
+        @Endpoint(getUserEndpoint)
+        async internalEndpoint(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: 'internal', name: 'hidden' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+})

package/src/legacy-compat/__type-tests__/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false,
+    "outDir": "../../../dist/legacy-compat/__type-tests__"
+  },
+  "include": ["**/*.spec-d.mts"],
+  "exclude": [],
+  "references": [
+    {
+      "path": "../../../tsconfig.lib.json"
+    }
+  ]
+}

package/src/legacy-compat/decorators/api-deprecated.decorator.mts

@@ -0,0 +1,46 @@
+import { LegacyAttributeFactory } from '@navios/core/legacy-compat'
+import { z } from 'zod/v4'
+
+import { ApiDeprecatedToken } from '../../tokens/index.mjs'
+
+const ApiDeprecatedSchema = z.object({
+  message: z.string().optional(),
+})
+
+/** Options for the @ApiDeprecated decorator, inferred from the schema */
+export type ApiDeprecatedOptions = z.infer<typeof ApiDeprecatedSchema>
+
+const BaseApiDeprecated = LegacyAttributeFactory.createAttribute(
+  ApiDeprecatedToken,
+  ApiDeprecatedSchema,
+)
+
+/**
+ * Marks an endpoint as deprecated.
+ *
+ * Deprecated endpoints are shown with a visual indicator in documentation
+ * and may include a migration message.
+ *
+ * Legacy-compatible version for TypeScript experimental decorators.
+ *
+ * @param message - Optional deprecation message
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   // Simple deprecation
+ *   @Endpoint(legacyGetUser)
+ *   @ApiDeprecated()
+ *   async getLegacyUser() {}
+ *
+ *   // With migration message
+ *   @Endpoint(oldCreateUser)
+ *   @ApiDeprecated('Use POST /v2/users instead')
+ *   async oldCreateUser() {}
+ * }
+ * ```
+ */
+export function ApiDeprecated(message?: string) {
+  return BaseApiDeprecated({ message })
+}

package/src/legacy-compat/decorators/api-exclude.decorator.mts

@@ -0,0 +1,31 @@
+import { LegacyAttributeFactory } from '@navios/core/legacy-compat'
+
+import { ApiExcludeToken } from '../../tokens/index.mjs'
+
+/**
+ * Excludes an endpoint from OpenAPI documentation.
+ *
+ * Use this decorator for internal endpoints that should not be visible
+ * in the public API documentation.
+ *
+ * Legacy-compatible version for TypeScript experimental decorators.
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class HealthController {
+ *   @Endpoint(healthCheck)
+ *   @ApiExclude()
+ *   async healthCheck() {
+ *     return { status: 'ok' }
+ *   }
+ *
+ *   @Endpoint(internalMetrics)
+ *   @ApiExclude()
+ *   async internalMetrics() {
+ *     return { ... }
+ *   }
+ * }
+ * ```
+ */
+export const ApiExclude = LegacyAttributeFactory.createAttribute(ApiExcludeToken)