@navios/openapi 0.7.0

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

@@ -0,0 +1,42 @@
+import type { ControllerMetadata, HandlerMetadata, ModuleMetadata } from '@navios/core';
+import type { BaseEndpointConfig } from '@navios/builder';
+import type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.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.
+ */
+export declare class EndpointScannerService {
+    private readonly logger;
+    private readonly metadataExtractor;
+    /**
+     * 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[];
+    /**
+     * Scans a controller and returns its endpoints
+     */
+    private scanController;
+}
+//# sourceMappingURL=endpoint-scanner.service.d.mts.map

package/dist/src/services/endpoint-scanner.service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-scanner.service.d.mts","sourceRoot":"","sources":["../../../src/services/endpoint-scanner.service.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACf,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAIzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAI/E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,MAAM,EAAE,cAAc,CAAA;IACtB,uBAAuB;IACvB,eAAe,EAAE,GAAG,CAAA;IACpB,0BAA0B;IAC1B,UAAU,EAAE,kBAAkB,CAAA;IAC9B,kCAAkC;IAClC,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,CAAA;IAC7B,kDAAkD;IAClD,MAAM,EAAE,kBAAkB,CAAA;IAC1B,iCAAiC;IACjC,eAAe,EAAE,uBAAuB,CAAA;CACzC;AAED;;;;;GAKG;AACH,qBACa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmC;IAErE;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,kBAAkB,EAAE;IAyBhE;;OAEG;IACH,OAAO,CAAC,cAAc;CAsCvB"}

package/dist/src/services/index.d.mts

@@ -0,0 +1,6 @@
+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';
+//# sourceMappingURL=index.d.mts.map

package/dist/src/services/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/services/index.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAE3E,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EACL,uBAAuB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA"}

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

@@ -0,0 +1,19 @@
+import type { ControllerMetadata, HandlerMetadata } from '@navios/core';
+import type { OpenApiEndpointMetadata } from '../metadata/openapi.metadata.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.
+ */
+export declare 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;
+}
+//# sourceMappingURL=metadata-extractor.service.d.mts.map

package/dist/src/services/metadata-extractor.service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-extractor.service.d.mts","sourceRoot":"","sources":["../../../src/services/metadata-extractor.service.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAIvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAY/E;;;;;GAKG;AACH,qBACa,wBAAwB;IACnC;;;;;;OAMG;IACH,OAAO,CACL,UAAU,EAAE,kBAAkB,EAC9B,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,GAC5B,uBAAuB;CAwD3B"}

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

@@ -0,0 +1,91 @@
+import type { ModuleMetadata } from '@navios/core';
+import type { oas31 } from 'zod-openapi';
+type OpenAPIObject = oas31.OpenAPIObject;
+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.
+ */
+export declare class OpenApiGeneratorService {
+    private readonly logger;
+    private readonly scanner;
+    private readonly pathBuilder;
+    /**
+     * 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;
+    /**
+     * Builds paths object from discovered endpoints
+     */
+    private buildPaths;
+    /**
+     * Collects unique tags from endpoints
+     */
+    private collectTags;
+    /**
+     * Merges discovered tags with configured tags
+     */
+    private mergeTags;
+}
+export {};
+//# sourceMappingURL=openapi-generator.service.d.mts.map

package/dist/src/services/openapi-generator.service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-generator.service.d.mts","sourceRoot":"","sources":["../../../src/services/openapi-generator.service.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AASxC,KAAK,aAAa,GAAG,KAAK,CAAC,aAAa,CAAA;AAExC,KAAK,oBAAoB,GAAG,KAAK,CAAC,oBAAoB,CAAA;AACtD,KAAK,SAAS,GAAG,KAAK,CAAC,SAAS,CAAA;AAEhC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAA;QACb,OAAO,EAAE,MAAM,CAAA;QACf,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,OAAO,CAAC,EAAE;YACR,IAAI,CAAC,EAAE,MAAM,CAAA;YACb,GAAG,CAAC,EAAE,MAAM,CAAA;YACZ,KAAK,CAAC,EAAE,MAAM,CAAA;SACf,CAAA;QACD,OAAO,CAAC,EAAE;YACR,IAAI,EAAE,MAAM,CAAA;YACZ,GAAG,CAAC,EAAE,MAAM,CAAA;SACb,CAAA;KACF,CAAA;IAED;;OAEG;IACH,YAAY,CAAC,EAAE;QACb,GAAG,EAAE,MAAM,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;IAED;;OAEG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,GAAG,EAAE,MAAM,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,SAAS,CAAC,EAAE,MAAM,CAChB,MAAM,EACN;YACE,OAAO,EAAE,MAAM,CAAA;YACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;YACf,WAAW,CAAC,EAAE,MAAM,CAAA;SACrB,CACF,CAAA;KACF,CAAC,CAAA;IAEF;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;IAEtD;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAE1C;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,EAAE,CAAA;CACnB;AAED;;;;GAIG;AACH,qBACa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD;;;;;;OAMG;IACH,QAAQ,CACN,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACpC,OAAO,EAAE,uBAAuB,GAC/B,aAAa;IAqDhB;;OAEG;IACH,OAAO,CAAC,UAAU;IAoBlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,CAAC,SAAS;CAsBlB"}

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

@@ -0,0 +1,73 @@
+import type { HandlerMetadata } from '@navios/core';
+import type { oas31 } from 'zod-openapi';
+import type { DiscoveredEndpoint } from './endpoint-scanner.service.mjs';
+type PathItemObject = oas31.PathItemObject;
+/**
+ * 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.
+ */
+export declare class PathBuilderService {
+    private readonly schemaConverter;
+    /**
+     * 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;
+    /**
+     * Converts Navios URL param format ($param) to OpenAPI format ({param})
+     */
+    convertUrlParams(url: string): string;
+    /**
+     * Extracts URL parameter names from a URL pattern
+     */
+    extractUrlParamNames(url: string): string[];
+    /**
+     * Gets the endpoint type based on the adapter token
+     */
+    getEndpointType(handler: HandlerMetadata<any>): 'endpoint' | 'multipart' | 'stream';
+    /**
+     * Builds OpenAPI parameters from endpoint config
+     */
+    private buildParameters;
+    /**
+     * Builds request body based on endpoint type
+     */
+    private buildRequestBody;
+    /**
+     * Builds request body for JSON endpoints
+     */
+    private buildJsonRequestBody;
+    /**
+     * Builds request body for multipart endpoints
+     */
+    private buildMultipartRequestBody;
+    /**
+     * Builds responses based on endpoint type
+     */
+    private buildResponses;
+    /**
+     * Builds responses for JSON endpoints
+     */
+    private buildJsonResponses;
+    /**
+     * Builds responses for stream endpoints
+     */
+    private buildStreamResponses;
+    /**
+     * Gets content object for different stream types
+     */
+    private getStreamContent;
+}
+export {};
+//# sourceMappingURL=path-builder.service.d.mts.map

package/dist/src/services/path-builder.service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-builder.service.d.mts","sourceRoot":"","sources":["../../../src/services/path-builder.service.mts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAUxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAOxE,KAAK,cAAc,GAAG,KAAK,CAAC,cAAc,CAAA;AAK1C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED;;;;;GAKG;AACH,qBACa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IAEjE;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,kBAAkB,GAAG,cAAc;IAgCnD;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIrC;;OAEG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAK3C;;OAEG;IACH,eAAe,CACb,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,GAC5B,UAAU,GAAG,WAAW,GAAG,QAAQ;IAUtC;;OAEG;IACH,OAAO,CAAC,eAAe;IAoCvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAmCjC;;OAEG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAyCzB"}

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

@@ -0,0 +1,57 @@
+import type { ZodType } from 'zod/v4';
+import type { oas31 } 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.
+ */
+export declare 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;
+    /**
+     * 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;
+    /**
+     * 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>;
+}
+export {};
+//# sourceMappingURL=schema-converter.service.d.mts.map

package/dist/src/services/schema-converter.service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-converter.service.d.mts","sourceRoot":"","sources":["../../../src/services/schema-converter.service.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAKxC,KAAK,YAAY,GAAG,KAAK,CAAC,YAAY,CAAA;AACtC,KAAK,eAAe,GAAG,KAAK,CAAC,eAAe,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAA;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACzC;AAED;;;;;GAKG;AACH,qBACa,sBAAsB;IACjC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB;IAIhD;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAI3C;;;;;;;OAOG;IACH,uBAAuB,CACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;CA2BhC"}

package/dist/src/tokens/index.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Tokens for OpenAPI metadata attributes
+ */
+/** Token for @ApiTag decorator */
+export declare const ApiTagToken: unique symbol;
+/** Token for @ApiOperation decorator */
+export declare const ApiOperationToken: unique symbol;
+/** Token for @ApiSummary decorator */
+export declare const ApiSummaryToken: unique symbol;
+/** Token for @ApiDeprecated decorator */
+export declare const ApiDeprecatedToken: unique symbol;
+/** Token for @ApiSecurity decorator */
+export declare const ApiSecurityToken: unique symbol;
+/** Token for @ApiExclude decorator */
+export declare const ApiExcludeToken: unique symbol;
+/** Token for @ApiStream decorator */
+export declare const ApiStreamToken: unique symbol;
+//# sourceMappingURL=index.d.mts.map

package/dist/src/tokens/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/tokens/index.mts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kCAAkC;AAClC,eAAO,MAAM,WAAW,eAAmC,CAAA;AAE3D,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,eAAyC,CAAA;AAEvE,sCAAsC;AACtC,eAAO,MAAM,eAAe,eAAuC,CAAA;AAEnE,yCAAyC;AACzC,eAAO,MAAM,kBAAkB,eAA0C,CAAA;AAEzE,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,eAAwC,CAAA;AAErE,sCAAsC;AACtC,eAAO,MAAM,eAAe,eAAuC,CAAA;AAEnE,qCAAqC;AACrC,eAAO,MAAM,cAAc,eAAsC,CAAA"}