@navios/openapi 0.9.1 → 1.0.0-alpha.3

package/src/__tests__/openapi-generator.service.spec.mts

@@ -0,0 +1,394 @@
+import type { ModuleMetadata } from '@navios/core'
+
+import { Logger } from '@navios/core'
+import { TestContainer } from '@navios/di/testing'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { DiscoveredEndpoint } from '../services/endpoint-scanner.service.mjs'
+import type { OpenApiGeneratorOptions } from '../services/openapi-generator.service.mjs'
+
+import { EndpointScannerService } from '../services/endpoint-scanner.service.mjs'
+import { OpenApiGeneratorService } from '../services/openapi-generator.service.mjs'
+import { PathBuilderService } from '../services/path-builder.service.mjs'
+
+// Mock logger
+const mockLogger = {
+  debug: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+}
+
+// Mock scanner
+const mockScanner = {
+  scan: vi.fn().mockReturnValue([]),
+}
+
+// Mock path builder
+const mockPathBuilder = {
+  build: vi.fn().mockReturnValue({
+    path: '/test',
+    pathItem: { get: { responses: { 200: { description: 'OK' } } } },
+  }),
+}
+
+describe('OpenApiGeneratorService', () => {
+  let container: TestContainer
+
+  beforeEach(() => {
+    container = new TestContainer()
+    // Bind required dependencies
+    container.bind(Logger).toValue(mockLogger as any)
+    container.bind(EndpointScannerService).toValue(mockScanner as any)
+    container.bind(PathBuilderService).toValue(mockPathBuilder as any)
+    vi.clearAllMocks()
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('generate', () => {
+    it('should generate basic OpenAPI document', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.openapi).toBe('3.1.0')
+      expect(document.info.title).toBe('Test API')
+      expect(document.info.version).toBe('1.0.0')
+      expect(document.paths).toBeDefined()
+    })
+
+    it('should include optional info fields', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+          description: 'A test API',
+          termsOfService: 'https://example.com/terms',
+          contact: {
+            name: 'Support',
+            email: 'support@example.com',
+            url: 'https://example.com',
+          },
+          license: {
+            name: 'MIT',
+            url: 'https://opensource.org/licenses/MIT',
+          },
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.info.description).toBe('A test API')
+      expect(document.info.termsOfService).toBe('https://example.com/terms')
+      expect(document.info.contact?.name).toBe('Support')
+      expect(document.info.license?.name).toBe('MIT')
+    })
+
+    it('should include servers when provided', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        servers: [
+          { url: 'https://api.example.com', description: 'Production' },
+          { url: 'https://staging.example.com', description: 'Staging' },
+        ],
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.servers).toHaveLength(2)
+      expect(document.servers?.[0].url).toBe('https://api.example.com')
+      expect(document.servers?.[1].description).toBe('Staging')
+    })
+
+    it('should not include servers when empty array', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        servers: [],
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.servers).toBeUndefined()
+    })
+
+    it('should include external docs when provided', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        externalDocs: {
+          url: 'https://docs.example.com',
+          description: 'Full documentation',
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.externalDocs?.url).toBe('https://docs.example.com')
+      expect(document.externalDocs?.description).toBe('Full documentation')
+    })
+
+    it('should include security schemes when provided', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+          },
+          apiKey: {
+            type: 'apiKey',
+            in: 'header',
+            name: 'X-API-Key',
+          },
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.components?.securitySchemes).toBeDefined()
+      const bearerAuth = document.components?.securitySchemes?.bearerAuth
+      const apiKey = document.components?.securitySchemes?.apiKey
+      expect(
+        bearerAuth && 'type' in bearerAuth ? bearerAuth.type : undefined,
+      ).toBe('http')
+      expect(apiKey && 'type' in apiKey ? apiKey.type : undefined).toBe(
+        'apiKey',
+      )
+    })
+
+    it('should include global security requirements', async () => {
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        security: [{ bearerAuth: [] }],
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.security).toHaveLength(1)
+      expect(document.security?.[0]).toEqual({ bearerAuth: [] })
+    })
+
+    it('should build paths from discovered endpoints', async () => {
+      const mockEndpoints: DiscoveredEndpoint[] = [
+        {
+          module: {} as any,
+          controllerClass: class {},
+          controller: {} as any,
+          handler: { config: { method: 'GET', url: '/users' } } as any,
+          config: { method: 'GET', url: '/users' },
+          openApiMetadata: {
+            tags: ['users'],
+            summary: '',
+            description: '',
+            operationId: '',
+            deprecated: false,
+            excluded: false,
+            security: [],
+          },
+        },
+      ]
+
+      mockScanner.scan.mockReturnValue(mockEndpoints)
+      mockPathBuilder.build.mockReturnValue({
+        path: '/users',
+        pathItem: {
+          get: { tags: ['users'], responses: { 200: { description: 'OK' } } },
+        },
+      })
+
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(mockScanner.scan).toHaveBeenCalledWith(modules)
+      expect(mockPathBuilder.build).toHaveBeenCalledWith(mockEndpoints[0])
+      expect(document.paths?.['/users']).toBeDefined()
+    })
+
+    it('should merge paths with different methods', async () => {
+      const mockEndpoints: DiscoveredEndpoint[] = [
+        {
+          module: {} as any,
+          controllerClass: class {},
+          controller: {} as any,
+          handler: { config: { method: 'GET', url: '/users' } } as any,
+          config: { method: 'GET', url: '/users' },
+          openApiMetadata: { tags: ['users'], excluded: false } as any,
+        },
+        {
+          module: {} as any,
+          controllerClass: class {},
+          controller: {} as any,
+          handler: { config: { method: 'POST', url: '/users' } } as any,
+          config: { method: 'POST', url: '/users' },
+          openApiMetadata: { tags: ['users'], excluded: false } as any,
+        },
+      ]
+
+      mockScanner.scan.mockReturnValue(mockEndpoints)
+      mockPathBuilder.build
+        .mockReturnValueOnce({
+          path: '/users',
+          pathItem: { get: { responses: { 200: { description: 'OK' } } } },
+        })
+        .mockReturnValueOnce({
+          path: '/users',
+          pathItem: {
+            post: { responses: { 201: { description: 'Created' } } },
+          },
+        })
+
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.paths?.['/users']?.get).toBeDefined()
+      expect(document.paths?.['/users']?.post).toBeDefined()
+    })
+
+    it('should collect and merge tags', async () => {
+      const mockEndpoints: DiscoveredEndpoint[] = [
+        {
+          module: {} as any,
+          controllerClass: class {},
+          controller: {} as any,
+          handler: {} as any,
+          config: {} as any,
+          openApiMetadata: { tags: ['users', 'api'], excluded: false } as any,
+        },
+        {
+          module: {} as any,
+          controllerClass: class {},
+          controller: {} as any,
+          handler: {} as any,
+          config: {} as any,
+          openApiMetadata: { tags: ['orders'], excluded: false } as any,
+        },
+      ]
+
+      mockScanner.scan.mockReturnValue(mockEndpoints)
+
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        tags: [{ name: 'users', description: 'User operations' }],
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.tags).toBeDefined()
+      expect(document.tags).toContainEqual({
+        name: 'users',
+        description: 'User operations',
+      })
+      expect(document.tags).toContainEqual({ name: 'api' })
+      expect(document.tags).toContainEqual({ name: 'orders' })
+    })
+
+    it('should not include tags when none discovered and none configured', async () => {
+      mockScanner.scan.mockReturnValue([])
+
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+      }
+
+      const document = generator.generate(modules, options)
+
+      expect(document.tags).toBeUndefined()
+    })
+
+    it('should log generation info', async () => {
+      mockScanner.scan.mockReturnValue([])
+
+      const generator = await container.get(OpenApiGeneratorService)
+
+      const modules = new Map<string, ModuleMetadata>()
+      const options: OpenApiGeneratorOptions = {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+      }
+
+      generator.generate(modules, options)
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'Generating OpenAPI document',
+      )
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining('Generated OpenAPI document'),
+      )
+    })
+  })
+})

package/src/__tests__/services.spec.mts

@@ -1,4 +1,4 @@
-import { TestContainer } from '@navios/di/testing'
+import { TestContainer } from '@navios/core/testing'
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { z } from 'zod/v4'

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

@@ -1,11 +1,16 @@
+import type { BaseEndpointOptions, EndpointOptions } from '@navios/builder'
 import type {
   ControllerMetadata,
   HandlerMetadata,
   ModuleMetadata,
 } from '@navios/core'
-import type { BaseEndpointConfig } from '@navios/builder'
 
-import { extractControllerMetadata, inject, Injectable, Logger } from '@navios/core'
+import {
+  extractControllerMetadata,
+  inject,
+  Injectable,
+  Logger,
+} from '@navios/core'
 
 import type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.mjs'
 
@@ -24,7 +29,7 @@ export interface DiscoveredEndpoint {
   /** Handler (endpoint) metadata */
   handler: HandlerMetadata<any>
   /** Endpoint configuration from @navios/builder */
-  config: BaseEndpointConfig
+  config: EndpointOptions | BaseEndpointOptions
   /** Extracted OpenAPI metadata */
   openApiMetadata: OpenApiEndpointMetadata
 }
@@ -53,7 +58,10 @@ export class EndpointScannerService {
     const endpoints: DiscoveredEndpoint[] = []
 
     for (const [moduleName, moduleMetadata] of modules) {
-      if (!moduleMetadata.controllers || moduleMetadata.controllers.size === 0) {
+      if (
+        !moduleMetadata.controllers ||
+        moduleMetadata.controllers.size === 0
+      ) {
         continue
       }
 
@@ -97,9 +105,7 @@ export class EndpointScannerService {
 
       // Skip excluded endpoints
       if (openApiMetadata.excluded) {
-        this.logger.debug(
-          `Skipping excluded endpoint: ${handler.classMethod}`,
-        )
+        this.logger.debug(`Skipping excluded endpoint: ${handler.classMethod}`)
         continue
       }
 
@@ -108,7 +114,7 @@ export class EndpointScannerService {
         controllerClass,
         controller: controllerMeta,
         handler,
-        config: handler.config as BaseEndpointConfig,
+        config: handler.config as EndpointOptions | BaseEndpointOptions,
         openApiMetadata,
       })
     }

package/src/services/path-builder.service.mts

@@ -1,4 +1,8 @@
-import type { BaseEndpointConfig } from '@navios/builder'
+import type {
+  BaseEndpointOptions,
+  EndpointOptions,
+  ErrorSchemaRecord,
+} from '@navios/builder'
 import type { HandlerMetadata } from '@navios/core'
 import type { oas31 } from 'zod-openapi'
 
@@ -60,8 +64,8 @@ export class PathBuilderService {
       deprecated: openApiMetadata.deprecated || undefined,
       externalDocs: openApiMetadata.externalDocs,
       security: openApiMetadata.security,
-      parameters: this.buildParameters(config),
-      requestBody: this.buildRequestBody(config, handler),
+      parameters: this.buildParameters(config as EndpointOptions),
+      requestBody: this.buildRequestBody(config as EndpointOptions, handler),
       responses: this.buildResponses(endpoint),
     }
 
@@ -98,20 +102,23 @@ export class PathBuilderService {
    */
   getEndpointType(
     handler: HandlerMetadata<any>,
-  ): 'endpoint' | 'multipart' | 'stream' {
+  ): 'endpoint' | 'multipart' | 'stream' | 'unknown' {
+    if (handler.adapterToken === EndpointAdapterToken) {
+      return 'endpoint'
+    }
     if (handler.adapterToken === MultipartAdapterToken) {
       return 'multipart'
     }
     if (handler.adapterToken === StreamAdapterToken) {
       return 'stream'
     }
-    return 'endpoint'
+    return 'unknown'
   }
 
   /**
    * Builds OpenAPI parameters from endpoint config
    */
-  private buildParameters(config: BaseEndpointConfig): ParameterObject[] {
+  private buildParameters(config: EndpointOptions): ParameterObject[] {
     const params: ParameterObject[] = []
 
     // URL parameters (from $paramName in URL)
@@ -151,7 +158,7 @@ export class PathBuilderService {
    * Builds request body based on endpoint type
    */
   private buildRequestBody(
-    config: BaseEndpointConfig,
+    config: EndpointOptions,
     handler: HandlerMetadata<any>,
   ): RequestBodyObject | undefined {
     const type = this.getEndpointType(handler)
@@ -171,7 +178,7 @@ export class PathBuilderService {
    * Builds request body for JSON endpoints
    */
   private buildJsonRequestBody(
-    config: BaseEndpointConfig,
+    config: EndpointOptions,
   ): RequestBodyObject | undefined {
     if (!config.requestSchema) {
       return undefined
@@ -193,7 +200,7 @@ export class PathBuilderService {
    * Builds request body for multipart endpoints
    */
   private buildMultipartRequestBody(
-    config: BaseEndpointConfig,
+    config: EndpointOptions,
   ): RequestBodyObject {
     if (!config.requestSchema) {
       return {
@@ -206,7 +213,8 @@ export class PathBuilderService {
       }
     }
 
-    const schema = this.schemaConverter.convert(config.requestSchema).schema as SchemaObject
+    const schema = this.schemaConverter.convert(config.requestSchema)
+      .schema as SchemaObject
 
     // Transform schema properties to handle File types
     const properties = this.schemaConverter.transformFileProperties(
@@ -239,62 +247,112 @@ export class PathBuilderService {
         return this.buildStreamResponses(endpoint)
       case 'multipart':
       case 'endpoint':
+        return this.buildJsonResponses(config as EndpointOptions, handler)
+      case 'unknown':
+        return this.buildUnknownResponses(config)
       default:
-        return this.buildJsonResponses(config, handler)
+        return this.buildUnknownResponses(config)
     }
   }
 
+  /**
+   * Builds error responses from errorSchema
+   *
+   * @param errorSchema - Optional record mapping status codes to Zod schemas
+   * @returns ResponsesObject with error responses, or empty object if no errorSchema
+   */
+  private buildErrorResponses(
+    errorSchema?: ErrorSchemaRecord,
+  ): ResponsesObject {
+    if (!errorSchema) {
+      return {}
+    }
+
+    const errorResponses: ResponsesObject = {}
+
+    for (const [statusCode, schema] of Object.entries(errorSchema)) {
+      const { schema: convertedSchema } = this.schemaConverter.convert(schema)
+      errorResponses[statusCode] = {
+        description: `Error response (${statusCode})`,
+        content: {
+          'application/json': {
+            schema: convertedSchema,
+          },
+        },
+      }
+    }
+
+    return errorResponses
+  }
+
   /**
    * Builds responses for JSON endpoints
    */
   private buildJsonResponses(
-    config: BaseEndpointConfig,
+    config: EndpointOptions,
     handler: HandlerMetadata<any>,
   ): ResponsesObject {
     const successCode = handler.successStatusCode?.toString() ?? '200'
+    const responses: ResponsesObject = {}
 
+    // Build success response
     if (!config.responseSchema) {
-      return {
-        [successCode]: {
-          description: 'Successful response',
-        },
+      responses[successCode] = {
+        description: 'Successful response',
       }
-    }
-
-    const { schema } = this.schemaConverter.convert(config.responseSchema)
-
-    return {
-      [successCode]: {
+    } else {
+      const { schema } = this.schemaConverter.convert(config.responseSchema)
+      responses[successCode] = {
         description: 'Successful response',
         content: {
           'application/json': {
             schema,
           },
         },
-      },
+      }
     }
+
+    // Add error responses from errorSchema
+    Object.assign(responses, this.buildErrorResponses(config.errorSchema))
+
+    return responses
   }
 
   /**
    * Builds responses for stream endpoints
    */
   private buildStreamResponses(endpoint: DiscoveredEndpoint): ResponsesObject {
-    const { openApiMetadata, handler } = endpoint
+    const { config, openApiMetadata, handler } = endpoint
     const successCode = handler.successStatusCode?.toString() ?? '200'
 
     const contentType =
       openApiMetadata.stream?.contentType ?? 'application/octet-stream'
-    const description =
-      openApiMetadata.stream?.description ?? 'Stream response'
+    const description = openApiMetadata.stream?.description ?? 'Stream response'
 
     const content: ContentObject = this.getStreamContent(contentType)
 
-    return {
+    const responses: ResponsesObject = {
       [successCode]: {
         description,
         content,
       },
     }
+
+    // Add error responses from errorSchema
+    Object.assign(responses, this.buildErrorResponses(config.errorSchema))
+
+    return responses
+  }
+
+  /**
+   * Builds responses for unknown endpoint types.
+   * Unknown types have no success response but can have error responses.
+   */
+  private buildUnknownResponses(
+    config: EndpointOptions | BaseEndpointOptions,
+  ): ResponsesObject {
+    // Only include error responses, no success response
+    return this.buildErrorResponses(config.errorSchema)
   }
 
   /**