@navios/openapi 0.7.0

package/src/services/endpoint-scanner.service.mts

@@ -0,0 +1,118 @@
+import type {
+  ControllerMetadata,
+  HandlerMetadata,
+  ModuleMetadata,
+} from '@navios/core'
+import type { BaseEndpointConfig } from '@navios/builder'
+
+import { extractControllerMetadata, inject, Injectable, Logger } from '@navios/core'
+
+import type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.mjs'
+
+import { MetadataExtractorService } from './metadata-extractor.service.mjs'
+
+/**
+ * Represents a discovered endpoint with all its metadata
+ */
+export interface DiscoveredEndpoint {
+  /** Module metadata */
+  module: ModuleMetadata
+  /** Controller class */
+  controllerClass: any
+  /** Controller metadata */
+  controller: ControllerMetadata
+  /** Handler (endpoint) metadata */
+  handler: HandlerMetadata<any>
+  /** Endpoint configuration from @navios/builder */
+  config: BaseEndpointConfig
+  /** Extracted OpenAPI metadata */
+  openApiMetadata: OpenApiEndpointMetadata
+}
+
+/**
+ * Service responsible for scanning modules and discovering endpoints.
+ *
+ * Iterates through all modules, controllers, and endpoints,
+ * extracting OpenAPI metadata from decorators.
+ */
+@Injectable()
+export class EndpointScannerService {
+  private readonly logger = inject(Logger, {
+    context: EndpointScannerService.name,
+  })
+
+  private readonly metadataExtractor = inject(MetadataExtractorService)
+
+  /**
+   * Scans all loaded modules and discovers endpoints.
+   *
+   * @param modules - Map of loaded modules from NaviosApplication
+   * @returns Array of discovered endpoints
+   */
+  scan(modules: Map<string, ModuleMetadata>): DiscoveredEndpoint[] {
+    const endpoints: DiscoveredEndpoint[] = []
+
+    for (const [moduleName, moduleMetadata] of modules) {
+      if (!moduleMetadata.controllers || moduleMetadata.controllers.size === 0) {
+        continue
+      }
+
+      this.logger.debug(`Scanning module: ${moduleName}`)
+
+      for (const controllerClass of moduleMetadata.controllers) {
+        const controllerMeta = extractControllerMetadata(controllerClass)
+        const controllerEndpoints = this.scanController(
+          moduleMetadata,
+          controllerClass,
+          controllerMeta,
+        )
+        endpoints.push(...controllerEndpoints)
+      }
+    }
+
+    this.logger.debug(`Discovered ${endpoints.length} endpoints`)
+    return endpoints
+  }
+
+  /**
+   * Scans a controller and returns its endpoints
+   */
+  private scanController(
+    module: ModuleMetadata,
+    controllerClass: any,
+    controllerMeta: ControllerMetadata,
+  ): DiscoveredEndpoint[] {
+    const endpoints: DiscoveredEndpoint[] = []
+
+    for (const handler of controllerMeta.endpoints) {
+      // Skip endpoints without config (non-builder endpoints)
+      if (!handler.config) {
+        continue
+      }
+
+      const openApiMetadata = this.metadataExtractor.extract(
+        controllerMeta,
+        handler,
+      )
+
+      // Skip excluded endpoints
+      if (openApiMetadata.excluded) {
+        this.logger.debug(
+          `Skipping excluded endpoint: ${handler.classMethod}`,
+        )
+        continue
+      }
+
+      endpoints.push({
+        module,
+        controllerClass,
+        controller: controllerMeta,
+        handler,
+        config: handler.config as BaseEndpointConfig,
+        openApiMetadata,
+      })
+    }
+
+    return endpoints
+  }
+}

package/src/services/index.mts

@@ -0,0 +1,21 @@
+export {
+  EndpointScannerService,
+  type DiscoveredEndpoint,
+} from './endpoint-scanner.service.mjs'
+
+export { MetadataExtractorService } from './metadata-extractor.service.mjs'
+
+export {
+  SchemaConverterService,
+  type SchemaConversionResult,
+} from './schema-converter.service.mjs'
+
+export {
+  PathBuilderService,
+  type PathItemResult,
+} from './path-builder.service.mjs'
+
+export {
+  OpenApiGeneratorService,
+  type OpenApiGeneratorOptions,
+} from './openapi-generator.service.mjs'

package/src/services/metadata-extractor.service.mts

@@ -0,0 +1,91 @@
+import type { ControllerMetadata, HandlerMetadata } from '@navios/core'
+
+import { Injectable } from '@navios/core'
+
+import type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.mjs'
+
+import {
+  ApiDeprecatedToken,
+  ApiExcludeToken,
+  ApiOperationToken,
+  ApiSecurityToken,
+  ApiStreamToken,
+  ApiSummaryToken,
+  ApiTagToken,
+} from '../tokens/index.mjs'
+
+/**
+ * Service responsible for extracting OpenAPI metadata from decorators.
+ *
+ * Merges controller-level and handler-level metadata to produce
+ * a complete OpenAPI metadata object for each endpoint.
+ */
+@Injectable()
+export class MetadataExtractorService {
+  /**
+   * Extracts and merges OpenAPI metadata from controller and handler.
+   *
+   * @param controller - Controller metadata
+   * @param handler - Handler metadata
+   * @returns Merged OpenAPI metadata
+   */
+  extract(
+    controller: ControllerMetadata,
+    handler: HandlerMetadata<any>,
+  ): OpenApiEndpointMetadata {
+    // Extract controller-level metadata
+    const controllerTag = controller.customAttributes.get(ApiTagToken) as
+      | { name: string; description?: string }
+      | undefined
+
+    // Extract handler-level metadata
+    const handlerTag = handler.customAttributes.get(ApiTagToken) as
+      | { name: string; description?: string }
+      | undefined
+    const operation = handler.customAttributes.get(ApiOperationToken) as
+      | {
+          summary?: string
+          description?: string
+          operationId?: string
+          deprecated?: boolean
+          externalDocs?: { url: string; description?: string }
+        }
+      | undefined
+    const summary = handler.customAttributes.get(ApiSummaryToken) as
+      | string
+      | undefined
+    const deprecated = handler.customAttributes.get(ApiDeprecatedToken) as
+      | { message?: string }
+      | undefined
+    const security = handler.customAttributes.get(ApiSecurityToken) as
+      | Record<string, string[]>
+      | undefined
+    const excluded = handler.customAttributes.get(ApiExcludeToken) as
+      | boolean
+      | undefined
+    const stream = handler.customAttributes.get(ApiStreamToken) as
+      | { contentType: string; description?: string }
+      | undefined
+
+    // Build tags array (handler tag takes precedence but both are included)
+    const tags: string[] = []
+    if (controllerTag?.name) {
+      tags.push(controllerTag.name)
+    }
+    if (handlerTag?.name && handlerTag.name !== controllerTag?.name) {
+      tags.push(handlerTag.name)
+    }
+
+    return {
+      tags,
+      summary: operation?.summary ?? summary,
+      description: operation?.description,
+      operationId: operation?.operationId,
+      deprecated: deprecated !== undefined || operation?.deprecated === true,
+      externalDocs: operation?.externalDocs,
+      security: security ? [security] : undefined,
+      excluded: excluded === true,
+      stream,
+    }
+  }
+}

package/src/services/openapi-generator.service.mts

@@ -0,0 +1,219 @@
+import type { ModuleMetadata } from '@navios/core'
+import type { oas31 } from 'zod-openapi'
+
+import { inject, Injectable, Logger } from '@navios/core'
+
+import type { DiscoveredEndpoint } from './endpoint-scanner.service.mjs'
+
+import { EndpointScannerService } from './endpoint-scanner.service.mjs'
+import { PathBuilderService } from './path-builder.service.mjs'
+
+type OpenAPIObject = oas31.OpenAPIObject
+type PathsObject = oas31.PathsObject
+type SecuritySchemeObject = oas31.SecuritySchemeObject
+type TagObject = oas31.TagObject
+
+/**
+ * Options for generating the OpenAPI document
+ */
+export interface OpenApiGeneratorOptions {
+  /**
+   * OpenAPI document info
+   */
+  info: {
+    title: string
+    version: string
+    description?: string
+    termsOfService?: string
+    contact?: {
+      name?: string
+      url?: string
+      email?: string
+    }
+    license?: {
+      name: string
+      url?: string
+    }
+  }
+
+  /**
+   * External documentation
+   */
+  externalDocs?: {
+    url: string
+    description?: string
+  }
+
+  /**
+   * Server definitions
+   */
+  servers?: Array<{
+    url: string
+    description?: string
+    variables?: Record<
+      string,
+      {
+        default: string
+        enum?: string[]
+        description?: string
+      }
+    >
+  }>
+
+  /**
+   * Security scheme definitions
+   */
+  securitySchemes?: Record<string, SecuritySchemeObject>
+
+  /**
+   * Global security requirements
+   */
+  security?: Array<Record<string, string[]>>
+
+  /**
+   * Tag definitions with descriptions
+   */
+  tags?: TagObject[]
+}
+
+/**
+ * Service responsible for generating the complete OpenAPI document.
+ *
+ * Orchestrates endpoint discovery, path generation, and document assembly.
+ */
+@Injectable()
+export class OpenApiGeneratorService {
+  private readonly logger = inject(Logger, {
+    context: OpenApiGeneratorService.name,
+  })
+
+  private readonly scanner = inject(EndpointScannerService)
+  private readonly pathBuilder = inject(PathBuilderService)
+
+  /**
+   * Generates an OpenAPI document from loaded modules.
+   *
+   * @param modules - Map of loaded modules
+   * @param options - OpenAPI generation options
+   * @returns Complete OpenAPI document
+   */
+  generate(
+    modules: Map<string, ModuleMetadata>,
+    options: OpenApiGeneratorOptions,
+  ): OpenAPIObject {
+    this.logger.debug('Generating OpenAPI document')
+
+    // Discover all endpoints
+    const endpoints = this.scanner.scan(modules)
+
+    // Generate paths
+    const paths = this.buildPaths(endpoints)
+
+    // Collect unique tags from endpoints
+    const discoveredTags = this.collectTags(endpoints)
+
+    // Merge discovered tags with configured tags
+    const tags = this.mergeTags(discoveredTags, options.tags)
+
+    // Build the OpenAPI document
+    const document: OpenAPIObject = {
+      openapi: '3.1.0',
+      info: options.info,
+      paths,
+    }
+
+    // Add optional fields
+    if (options.servers && options.servers.length > 0) {
+      document.servers = options.servers
+    }
+
+    if (options.externalDocs) {
+      document.externalDocs = options.externalDocs
+    }
+
+    if (tags.length > 0) {
+      document.tags = tags
+    }
+
+    if (options.security) {
+      document.security = options.security
+    }
+
+    if (options.securitySchemes) {
+      document.components = {
+        ...document.components,
+        securitySchemes: options.securitySchemes,
+      }
+    }
+
+    this.logger.debug(
+      `Generated OpenAPI document with ${Object.keys(paths).length} paths`,
+    )
+
+    return document
+  }
+
+  /**
+   * Builds paths object from discovered endpoints
+   */
+  private buildPaths(endpoints: DiscoveredEndpoint[]): PathsObject {
+    const paths: PathsObject = {}
+
+    for (const endpoint of endpoints) {
+      const { path, pathItem } = this.pathBuilder.build(endpoint)
+
+      // Merge with existing path if methods differ
+      if (paths[path]) {
+        paths[path] = {
+          ...paths[path],
+          ...pathItem,
+        }
+      } else {
+        paths[path] = pathItem
+      }
+    }
+
+    return paths
+  }
+
+  /**
+   * Collects unique tags from endpoints
+   */
+  private collectTags(endpoints: DiscoveredEndpoint[]): Set<string> {
+    const tags = new Set<string>()
+
+    for (const endpoint of endpoints) {
+      for (const tag of endpoint.openApiMetadata.tags) {
+        tags.add(tag)
+      }
+    }
+
+    return tags
+  }
+
+  /**
+   * Merges discovered tags with configured tags
+   */
+  private mergeTags(
+    discoveredTags: Set<string>,
+    configuredTags?: TagObject[],
+  ): TagObject[] {
+    const tagMap = new Map<string, TagObject>()
+
+    // Add configured tags first (they have descriptions)
+    if (configuredTags) {
+      for (const tag of configuredTags) {
+        tagMap.set(tag.name, tag)
+      }
+    }
+
+    // Add discovered tags that aren't already configured
+    for (const tagName of discoveredTags) {
+      if (!tagMap.has(tagName)) {
+        tagMap.set(tagName, { name: tagName })
+      }
+    }
+
+    return Array.from(tagMap.values())
+  }
+}