@navios/openapi 0.7.0

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

@@ -0,0 +1,344 @@
+import type { BaseEndpointConfig } from '@navios/builder'
+import type { HandlerMetadata } from '@navios/core'
+import type { oas31 } from 'zod-openapi'
+
+import {
+  EndpointAdapterToken,
+  inject,
+  Injectable,
+  MultipartAdapterToken,
+  StreamAdapterToken,
+} from '@navios/core'
+
+import type { DiscoveredEndpoint } from './endpoint-scanner.service.mjs'
+
+import { SchemaConverterService } from './schema-converter.service.mjs'
+
+type ContentObject = oas31.ContentObject
+type OperationObject = oas31.OperationObject
+type ParameterObject = oas31.ParameterObject
+type PathItemObject = oas31.PathItemObject
+type RequestBodyObject = oas31.RequestBodyObject
+type ResponsesObject = oas31.ResponsesObject
+type SchemaObject = oas31.SchemaObject
+
+/**
+ * Result of path item generation
+ */
+export interface PathItemResult {
+  path: string
+  pathItem: PathItemObject
+}
+
+/**
+ * Service responsible for building OpenAPI path items from endpoints.
+ *
+ * Handles URL parameter conversion, request body generation,
+ * and response schema generation for different endpoint types.
+ */
+@Injectable()
+export class PathBuilderService {
+  private readonly schemaConverter = inject(SchemaConverterService)
+
+  /**
+   * Generates an OpenAPI path item for a discovered endpoint.
+   *
+   * @param endpoint - Discovered endpoint with metadata
+   * @returns Path string and path item object
+   */
+  build(endpoint: DiscoveredEndpoint): PathItemResult {
+    const { config, handler, openApiMetadata } = endpoint
+
+    // Convert $param to {param} format for OpenAPI
+    const path = this.convertUrlParams(config.url)
+
+    const operation: OperationObject = {
+      tags: openApiMetadata.tags.length > 0 ? openApiMetadata.tags : undefined,
+      summary: openApiMetadata.summary,
+      description: openApiMetadata.description,
+      operationId: openApiMetadata.operationId,
+      deprecated: openApiMetadata.deprecated || undefined,
+      externalDocs: openApiMetadata.externalDocs,
+      security: openApiMetadata.security,
+      parameters: this.buildParameters(config),
+      requestBody: this.buildRequestBody(config, handler),
+      responses: this.buildResponses(endpoint),
+    }
+
+    // Remove undefined properties
+    const cleanOperation = Object.fromEntries(
+      Object.entries(operation).filter(([, v]) => v !== undefined),
+    ) as OperationObject
+
+    return {
+      path,
+      pathItem: {
+        [config.method.toLowerCase()]: cleanOperation,
+      },
+    }
+  }
+
+  /**
+   * Converts Navios URL param format ($param) to OpenAPI format ({param})
+   */
+  convertUrlParams(url: string): string {
+    return url.replace(/\$(\w+)/g, '{$1}')
+  }
+
+  /**
+   * Extracts URL parameter names from a URL pattern
+   */
+  extractUrlParamNames(url: string): string[] {
+    const matches = url.matchAll(/\$(\w+)/g)
+    return Array.from(matches, (m) => m[1])
+  }
+
+  /**
+   * Gets the endpoint type based on the adapter token
+   */
+  getEndpointType(
+    handler: HandlerMetadata<any>,
+  ): 'endpoint' | 'multipart' | 'stream' {
+    if (handler.adapterToken === MultipartAdapterToken) {
+      return 'multipart'
+    }
+    if (handler.adapterToken === StreamAdapterToken) {
+      return 'stream'
+    }
+    return 'endpoint'
+  }
+
+  /**
+   * Builds OpenAPI parameters from endpoint config
+   */
+  private buildParameters(config: BaseEndpointConfig): ParameterObject[] {
+    const params: ParameterObject[] = []
+
+    // URL parameters (from $paramName in URL)
+    const urlParams = this.extractUrlParamNames(config.url)
+    for (const param of urlParams) {
+      params.push({
+        name: param,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      })
+    }
+
+    // Query parameters (from querySchema)
+    if (config.querySchema) {
+      const { schema: querySchema } = this.schemaConverter.convert(
+        config.querySchema,
+      )
+      const schemaObj = querySchema as SchemaObject
+      if (schemaObj.properties) {
+        for (const [name, schema] of Object.entries(schemaObj.properties)) {
+          params.push({
+            name,
+            in: 'query',
+            required: schemaObj.required?.includes(name) ?? false,
+            schema: schema as SchemaObject,
+            description: (schema as SchemaObject).description,
+          })
+        }
+      }
+    }
+
+    return params
+  }
+
+  /**
+   * Builds request body based on endpoint type
+   */
+  private buildRequestBody(
+    config: BaseEndpointConfig,
+    handler: HandlerMetadata<any>,
+  ): RequestBodyObject | undefined {
+    const type = this.getEndpointType(handler)
+
+    switch (type) {
+      case 'multipart':
+        return this.buildMultipartRequestBody(config)
+      case 'stream':
+        return undefined // Streams typically don't have request bodies
+      case 'endpoint':
+      default:
+        return this.buildJsonRequestBody(config)
+    }
+  }
+
+  /**
+   * Builds request body for JSON endpoints
+   */
+  private buildJsonRequestBody(
+    config: BaseEndpointConfig,
+  ): RequestBodyObject | undefined {
+    if (!config.requestSchema) {
+      return undefined
+    }
+
+    const { schema } = this.schemaConverter.convert(config.requestSchema)
+
+    return {
+      required: true,
+      content: {
+        'application/json': {
+          schema,
+        },
+      },
+    }
+  }
+
+  /**
+   * Builds request body for multipart endpoints
+   */
+  private buildMultipartRequestBody(
+    config: BaseEndpointConfig,
+  ): RequestBodyObject {
+    if (!config.requestSchema) {
+      return {
+        required: true,
+        content: {
+          'multipart/form-data': {
+            schema: { type: 'object' },
+          },
+        },
+      }
+    }
+
+    const schema = this.schemaConverter.convert(config.requestSchema).schema as SchemaObject
+
+    // Transform schema properties to handle File types
+    const properties = this.schemaConverter.transformFileProperties(
+      (schema.properties as Record<string, SchemaObject>) || {},
+    )
+
+    return {
+      required: true,
+      content: {
+        'multipart/form-data': {
+          schema: {
+            type: 'object',
+            properties,
+            required: schema.required,
+          },
+        },
+      },
+    }
+  }
+
+  /**
+   * Builds responses based on endpoint type
+   */
+  private buildResponses(endpoint: DiscoveredEndpoint): ResponsesObject {
+    const { config, handler } = endpoint
+    const type = this.getEndpointType(handler)
+
+    switch (type) {
+      case 'stream':
+        return this.buildStreamResponses(endpoint)
+      case 'multipart':
+      case 'endpoint':
+      default:
+        return this.buildJsonResponses(config, handler)
+    }
+  }
+
+  /**
+   * Builds responses for JSON endpoints
+   */
+  private buildJsonResponses(
+    config: BaseEndpointConfig,
+    handler: HandlerMetadata<any>,
+  ): ResponsesObject {
+    const successCode = handler.successStatusCode?.toString() ?? '200'
+
+    if (!config.responseSchema) {
+      return {
+        [successCode]: {
+          description: 'Successful response',
+        },
+      }
+    }
+
+    const { schema } = this.schemaConverter.convert(config.responseSchema)
+
+    return {
+      [successCode]: {
+        description: 'Successful response',
+        content: {
+          'application/json': {
+            schema,
+          },
+        },
+      },
+    }
+  }
+
+  /**
+   * Builds responses for stream endpoints
+   */
+  private buildStreamResponses(endpoint: DiscoveredEndpoint): ResponsesObject {
+    const { 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 content: ContentObject = this.getStreamContent(contentType)
+
+    return {
+      [successCode]: {
+        description,
+        content,
+      },
+    }
+  }
+
+  /**
+   * Gets content object for different stream types
+   */
+  private getStreamContent(contentType: string): ContentObject {
+    switch (contentType) {
+      case 'text/event-stream':
+        return {
+          'text/event-stream': {
+            schema: {
+              type: 'string',
+              description: 'Server-Sent Events stream',
+            },
+          },
+        }
+
+      case 'application/octet-stream':
+        return {
+          'application/octet-stream': {
+            schema: {
+              type: 'string',
+              format: 'binary',
+              description: 'Binary file download',
+            },
+          },
+        }
+
+      case 'application/json':
+        return {
+          'application/json': {
+            schema: {
+              type: 'string',
+              description: 'Newline-delimited JSON stream',
+            },
+          },
+        }
+
+      default:
+        return {
+          [contentType]: {
+            schema: { type: 'string', format: 'binary' },
+          },
+        }
+    }
+  }
+}

package/src/services/schema-converter.service.mts

@@ -0,0 +1,96 @@
+import type { ZodType } from 'zod/v4'
+import type { oas31 } from 'zod-openapi'
+
+import { Injectable } from '@navios/core'
+import { createSchema } from 'zod-openapi'
+
+type SchemaObject = oas31.SchemaObject
+type ReferenceObject = oas31.ReferenceObject
+
+/**
+ * Result of schema conversion
+ */
+export interface SchemaConversionResult {
+  schema: SchemaObject | ReferenceObject
+  components: Record<string, SchemaObject>
+}
+
+/**
+ * Service responsible for converting Zod schemas to OpenAPI schemas.
+ *
+ * Uses zod-openapi library which supports Zod 4's native `.meta()` method
+ * for OpenAPI-specific metadata.
+ */
+@Injectable()
+export class SchemaConverterService {
+  /**
+   * Converts a Zod schema to an OpenAPI schema object.
+   *
+   * @param schema - Zod schema to convert
+   * @returns OpenAPI schema object with any component schemas
+   *
+   * @example
+   * ```typescript
+   * const userSchema = z.object({
+   *   id: z.string().meta({ openapi: { example: 'usr_123' } }),
+   *   name: z.string(),
+   * })
+   *
+   * const result = schemaConverter.convert(userSchema)
+   * // { schema: { type: 'object', properties: { ... } }, components: {} }
+   * ```
+   */
+  convert(schema: ZodType): SchemaConversionResult {
+    return createSchema(schema)
+  }
+
+  /**
+   * Checks if a schema property represents a File type.
+   *
+   * Used for multipart form handling to convert File types to binary format.
+   *
+   * @param schema - Schema object to check
+   * @returns true if the schema represents a file
+   */
+  isFileSchema(schema: SchemaObject): boolean {
+    return schema.type === 'string' && schema.format === 'binary'
+  }
+
+  /**
+   * Transforms schema properties to handle File/Blob types for multipart.
+   *
+   * Converts File types to OpenAPI binary format and handles arrays of files.
+   *
+   * @param properties - Schema properties object
+   * @returns Transformed properties with file types as binary
+   */
+  transformFileProperties(
+    properties: Record<string, SchemaObject>,
+  ): Record<string, SchemaObject> {
+    const result: Record<string, SchemaObject> = {}
+
+    for (const [key, prop] of Object.entries(properties)) {
+      if (this.isFileSchema(prop)) {
+        result[key] = {
+          type: 'string',
+          format: 'binary',
+          description: prop.description,
+        }
+      } else if (
+        prop.type === 'array' &&
+        prop.items &&
+        this.isFileSchema(prop.items as SchemaObject)
+      ) {
+        result[key] = {
+          type: 'array',
+          items: { type: 'string', format: 'binary' },
+          description: prop.description,
+        }
+      } else {
+        result[key] = prop
+      }
+    }
+
+    return result
+  }
+}

package/src/tokens/index.mts

@@ -0,0 +1,24 @@
+/**
+ * Tokens for OpenAPI metadata attributes
+ */
+
+/** Token for @ApiTag decorator */
+export const ApiTagToken = Symbol.for('navios:openapi:tag')
+
+/** Token for @ApiOperation decorator */
+export const ApiOperationToken = Symbol.for('navios:openapi:operation')
+
+/** Token for @ApiSummary decorator */
+export const ApiSummaryToken = Symbol.for('navios:openapi:summary')
+
+/** Token for @ApiDeprecated decorator */
+export const ApiDeprecatedToken = Symbol.for('navios:openapi:deprecated')
+
+/** Token for @ApiSecurity decorator */
+export const ApiSecurityToken = Symbol.for('navios:openapi:security')
+
+/** Token for @ApiExclude decorator */
+export const ApiExcludeToken = Symbol.for('navios:openapi:exclude')
+
+/** Token for @ApiStream decorator */
+export const ApiStreamToken = Symbol.for('navios:openapi:stream')

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "Node18",
+    "outDir": "dist"
+  },
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    },
+    {
+      "path": "../core"
+    },
+    {
+      "path": "../di"
+    },
+    {
+      "path": "../builder"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.spec.mts", "src/**/*.spec-d.mts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*.spec.mts", "src/**/*.spec-d.mts"],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/tsdown.config.mts

@@ -0,0 +1,35 @@
+import { withFilter } from 'rolldown/filter'
+import { defineConfig } from 'tsdown'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  entry: ['src/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  tsconfig: 'tsconfig.lib.json',
+  treeshake: true,
+  sourcemap: true,
+  platform: 'node',
+  external: ['@navios/core', '@navios/di'],
+  dts: true,
+  target: 'es2022',
+  plugins: [
+    withFilter(
+      swc.rolldown({
+        jsc: {
+          target: 'es2022',
+          parser: {
+            syntax: 'typescript',
+            decorators: true,
+          },
+          transform: {
+            decoratorVersion: '2022-03',
+          },
+        },
+      }),
+      // Only run this transform if the file contains a decorator.
+      { transform: { code: '@' } },
+    ),
+  ],
+})

package/vitest.config.mts

@@ -0,0 +1,11 @@
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {
+    typecheck: {
+      enabled: true,
+      tsconfig: './tsconfig.lib.json',
+    },
+    include: ['src/**/*.spec.mts', 'src/**/*.spec-d.mts'],
+  },
+})