klasik 1.0.11 → 1.0.13

package/README.md

@@ -6,6 +6,8 @@ Download OpenAPI specifications from remote URLs and generate TypeScript clients
 
 - 📥 **Download OpenAPI specs** from remote URLs or local files
 - 📁 **Multiple input formats** - HTTP/HTTPS URLs, file:// URLs, absolute/relative paths
+- 🔐 **Authentication support** - Custom headers including Bearer tokens and API keys
+- 🔗 **External reference resolution** - Automatically download referenced schema files (`$ref`)
 - 🔄 **Automatic transformation** - Converts API responses to class instances using class-transformer
 - 🎯 **Type-safe** - Full TypeScript support with decorators
 - 🛠️ **Configurable** - Custom headers, timeouts, and templates
@@ -81,6 +83,9 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
   - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
 - `-o, --output <dir>` - Output directory for generated client code (required)
 - `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
+  - Can be used multiple times for multiple headers
+  - Perfect for authorization: `--header "Authorization: Bearer token"`
+- `-r, --resolve-refs` - Resolve and download external `$ref` references
 - `-t, --template <dir>` - Custom template directory
 - `-k, --keep-spec` - Keep the downloaded spec file after generation
 - `--timeout <ms>` - Request timeout in milliseconds for HTTP requests (default: 30000)
@@ -88,13 +93,27 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
 **Examples:**
 
 ```bash
-# From remote URL
+# From remote URL with authorization
 klasik generate \
   --url https://api.example.com/openapi.json \
   --output ./client \
   --header "Authorization: Bearer token123" \
   --timeout 60000
 
+# With external reference resolution
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token123" \
+  --resolve-refs
+
+# Multiple headers
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token" \
+  --header "X-API-Version: v1"
+
 # From local file
 klasik generate \
   --url ./my-spec.json \
@@ -114,15 +133,24 @@ Download an OpenAPI spec from a remote URL without generating code.
 - `-u, --url <url>` - Remote URL to download the OpenAPI spec from (required)
 - `-o, --output <file>` - Output file path for the downloaded spec (required)
 - `-H, --header <header...>` - Custom headers for the request
+- `-r, --resolve-refs` - Resolve and download external `$ref` references
 - `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
 
-**Example:**
+**Examples:**
 
 ```bash
+# Download spec only
 klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json \
   --header "Authorization: Bearer token123"
+
+# Download spec with all external references
+klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json \
+  --header "Authorization: Bearer token123" \
+  --resolve-refs
 ```
 
 ## Programmatic API
@@ -141,6 +169,7 @@ await generator.generate({
     'Authorization': 'Bearer token123',
     'X-Custom-Header': 'value'
   },
+  resolveReferences: true, // Download external $ref files
   templateDir: './custom-templates', // Optional
   keepSpec: true, // Keep downloaded spec file
   timeout: 60000 // Request timeout in ms
@@ -160,6 +189,7 @@ const specPath = await downloader.download({
   headers: {
     'Authorization': 'Bearer token123'
   },
+  resolveReferences: true, // Download external $ref files
   timeout: 30000
 });
 
@@ -235,6 +265,90 @@ const user = response.data; // user is instanceof User ✅
 console.log(user.name); // Fully typed!
 ```
 
+## External Reference Resolution
+
+Klasik can automatically resolve and download external `$ref` references in your OpenAPI specs. This is useful when your spec splits schemas across multiple files.
+
+### How It Works
+
+When you enable `--resolve-refs` (CLI) or `resolveReferences: true` (programmatic), klasik will:
+
+1. **Parse the main spec** for external `$ref` references
+2. **Download all referenced files** preserving directory structure
+3. **Recursively resolve nested references** in downloaded files
+4. **Use the same authentication** for all downloads
+
+### Example OpenAPI Spec with External References
+
+```json
+{
+  "openapi": "3.0.0",
+  "paths": {
+    "/users": {
+      "get": {
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "./schemas/users-orgs.yaml#/components/schemas/Org"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+With `--resolve-refs`, klasik will automatically download `./schemas/users-orgs.yaml` and any files it references.
+
+### Output Structure
+
+Referenced files are downloaded preserving the directory structure:
+
+```
+output/
+├── openapi-spec.json       # Main spec
+└── schemas/
+    ├── users-orgs.yaml     # Referenced schema
+    └── common/
+        └── types.yaml      # Nested reference
+```
+
+### Supported Reference Types
+
+- **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
+- **Remote URLs**: `https://api.example.com/schemas/user.yaml`
+- **Mixed**: Main spec from HTTPS, references can be relative or absolute
+
+### CLI Example
+
+```bash
+# Download spec with all external references
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token" \
+  --resolve-refs
+```
+
+### Programmatic Example
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+await new K8sClientGenerator().generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  headers: { 'Authorization': 'Bearer token' },
+  resolveReferences: true,
+  keepSpec: true // Keep all downloaded files
+});
+```
+
 ## Advanced Configuration
 
 ### Custom Error Handling

package/USAGE_EXAMPLES.md

@@ -0,0 +1,160 @@
+# Klasik Usage Examples
+
+## Using Custom Headers (Authorization)
+
+### CLI Example - Authorization Token
+
+```bash
+# Using Bearer token
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer your-token-here"
+
+# Using API key
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "X-API-Key: your-api-key"
+
+# Multiple headers
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer your-token" \
+  --header "X-Custom-Header: custom-value"
+```
+
+### Programmatic Example - Authorization Token
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  headers: {
+    'Authorization': 'Bearer your-token-here',
+    'X-API-Key': 'your-api-key'
+  }
+});
+```
+
+## Resolving External References
+
+### CLI Example - With Reference Resolution
+
+```bash
+# Download spec and all external $ref files
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --resolve-refs \
+  --header "Authorization: Bearer your-token"
+
+# Download only (no code generation)
+npx klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json \
+  --resolve-refs \
+  --header "Authorization: Bearer your-token"
+```
+
+### Programmatic Example - With Reference Resolution
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  resolveReferences: true,
+  headers: {
+    'Authorization': 'Bearer your-token-here'
+  }
+});
+```
+
+## How Reference Resolution Works
+
+When you enable `--resolve-refs` (or `resolveReferences: true`), klasik will:
+
+1. **Parse the main OpenAPI spec** for external `$ref` references like:
+   ```yaml
+   schema:
+     $ref: './schemas/users-orgs.yaml#/components/schemas/Org'
+   ```
+
+2. **Download all referenced files** preserving the directory structure:
+   ```
+   output/
+   ├── openapi-spec.json (main spec)
+   └── schemas/
+       └── users-orgs.yaml (referenced schema)
+   ```
+
+3. **Recursively resolve nested references** - if `users-orgs.yaml` has its own `$ref` to other files, those will be downloaded too
+
+4. **Use the same headers** for all downloads (useful when all files require authentication)
+
+### Supported Reference Types
+
+- **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
+- **Remote URLs**: `https://api.example.com/schemas/user.yaml`
+- **Mixed**: Main spec from HTTPS, references can be relative or absolute
+
+### Example OpenAPI Spec with External References
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "My API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "./schemas/users.yaml#/components/schemas/UserList"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+When you run with `--resolve-refs`, klasik will automatically download `./schemas/users.yaml`.
+
+## Complete Example
+
+```bash
+# Full workflow with private API
+npx klasik generate \
+  --url https://private-api.example.com/v1/openapi.json \
+  --output ./generated-client \
+  --header "Authorization: Bearer eyJhbGc..." \
+  --header "X-API-Version: v1" \
+  --resolve-refs \
+  --keep-spec \
+  --timeout 60000
+```
+
+This will:
+- Download the OpenAPI spec with authorization headers
+- Resolve and download all external schema references
+- Generate the TypeScript client
+- Keep all downloaded specs in the output directory
+- Use a 60-second timeout for all HTTP requests

package/dist/cli.js

@@ -51,6 +51,7 @@ program
     .option('-H, --header <header...>', 'Custom headers for the request (format: "Key: Value")')
     .option('-t, --template <dir>', 'Custom template directory')
     .option('-k, --keep-spec', 'Keep the downloaded spec file after generation', false)
+    .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -80,6 +81,7 @@ program
             headers: Object.keys(headers).length > 0 ? headers : undefined,
             templateDir: options.template,
             keepSpec: options.keepSpec,
+            resolveReferences: options.resolveRefs,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);
@@ -95,6 +97,7 @@ program
     .requiredOption('-u, --url <url>', 'Remote URL to download the OpenAPI spec from')
     .requiredOption('-o, --output <file>', 'Output file path for the downloaded spec')
     .option('-H, --header <header...>', 'Custom headers for the request (format: "Key: Value")')
+    .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -115,6 +118,7 @@ program
             url: options.url,
             outputPath: path.resolve(options.output),
             headers: Object.keys(headers).length > 0 ? headers : undefined,
+            resolveReferences: options.resolveRefs,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);

package/dist/k8s-client-generator.d.ts

@@ -28,6 +28,11 @@ export interface K8sClientGeneratorOptions {
      * @default false
      */
     keepSpec?: boolean;
+    /**
+     * Whether to resolve and download external $ref references
+     * @default false
+     */
+    resolveReferences?: boolean;
     /**
      * Request timeout for downloading spec in milliseconds
      * @default 30000

package/dist/k8s-client-generator.js

@@ -46,7 +46,7 @@ class K8sClientGenerator {
      * Generate TypeScript client from a remote OpenAPI spec URL
      */
     async generate(options) {
-        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, timeout, } = options;
+        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, timeout, } = options;
         let specPath;
         try {
             // Step 1: Download the OpenAPI spec
@@ -55,6 +55,7 @@ class K8sClientGenerator {
                 url: specUrl,
                 headers,
                 timeout,
+                resolveReferences,
                 // If keepSpec is true, save the spec in the output directory
                 outputPath: keepSpec ? path.join(outputDir, 'openapi-spec.json') : undefined,
             };

package/dist/spec-downloader.d.ts

@@ -22,8 +22,19 @@ export interface DownloadOptions {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Whether to resolve and download external $ref references
+     * @default false
+     */
+    resolveReferences?: boolean;
+    /**
+     * Base URL for resolving relative references (used when main spec is from HTTP)
+     * If not provided, will be derived from the main spec URL
+     */
+    baseUrl?: string;
 }
 export declare class SpecDownloader {
+    private downloadedRefs;
     /**
      * Download an OpenAPI specification from a URL or load from a local file
      * @param options Download options
@@ -50,4 +61,24 @@ export declare class SpecDownloader {
      * Clean up temporary files
      */
     cleanupTemp(): void;
+    /**
+     * Get base URL from a full URL (removes the filename)
+     */
+    private getBaseUrl;
+    /**
+     * Resolve and download all external $ref references in the spec
+     */
+    private resolveExternalRefs;
+    /**
+     * Find all external $ref values in the spec
+     */
+    private findExternalRefs;
+    /**
+     * Check if a $ref is external (references another file)
+     */
+    private isExternalRef;
+    /**
+     * Download a single reference file
+     */
+    private downloadReference;
 }

package/dist/spec-downloader.js

@@ -41,16 +41,25 @@ const axios_1 = __importDefault(require("axios"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 class SpecDownloader {
+    constructor() {
+        this.downloadedRefs = new Set();
+    }
     /**
      * Download an OpenAPI specification from a URL or load from a local file
      * @param options Download options
      * @returns Path to the spec file
      */
     async download(options) {
-        const { url, outputPath, headers, timeout = 30000 } = options;
+        const { url, outputPath, headers, timeout = 30000, resolveReferences = false, baseUrl } = options;
+        // Reset downloaded refs tracking for each new download
+        this.downloadedRefs.clear();
         // Check if it's a local file path
         if (this.isLocalFile(url)) {
-            return this.loadLocalFile(url, outputPath);
+            const specPath = await this.loadLocalFile(url, outputPath);
+            if (resolveReferences) {
+                await this.resolveExternalRefs(specPath, headers, timeout, baseUrl || path.dirname(specPath));
+            }
+            return specPath;
         }
         // Otherwise, download from HTTP/HTTPS
         console.log(`Downloading OpenAPI spec from ${url}...`);
@@ -88,6 +97,11 @@ class SpecDownloader {
             // Write to file
             fs.writeFileSync(specPath, specContent, 'utf-8');
             console.log(`OpenAPI spec downloaded successfully to ${specPath}`);
+            // Resolve references if requested
+            if (resolveReferences) {
+                const resolvedBaseUrl = baseUrl || this.getBaseUrl(url);
+                await this.resolveExternalRefs(specPath, headers, timeout, resolvedBaseUrl);
+            }
             return specPath;
         }
         catch (error) {
@@ -209,5 +223,161 @@ class SpecDownloader {
             console.log('Cleaned up temporary files');
         }
     }
+    /**
+     * Get base URL from a full URL (removes the filename)
+     */
+    getBaseUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            const pathParts = urlObj.pathname.split('/');
+            pathParts.pop(); // Remove filename
+            urlObj.pathname = pathParts.join('/');
+            return urlObj.toString();
+        }
+        catch {
+            // If URL parsing fails, return the original URL
+            return url;
+        }
+    }
+    /**
+     * Resolve and download all external $ref references in the spec
+     */
+    async resolveExternalRefs(specPath, headers, timeout, baseUrl) {
+        console.log('Resolving external references...');
+        const content = fs.readFileSync(specPath, 'utf-8');
+        let spec;
+        try {
+            spec = JSON.parse(content);
+        }
+        catch {
+            console.log('Spec is not JSON, skipping reference resolution');
+            return;
+        }
+        const refs = this.findExternalRefs(spec);
+        if (refs.length === 0) {
+            console.log('No external references found');
+            return;
+        }
+        console.log(`Found ${refs.length} external reference(s)`);
+        const specDir = path.dirname(specPath);
+        const isRemoteSpec = !this.isLocalFile(baseUrl || '');
+        for (const ref of refs) {
+            await this.downloadReference(ref, specDir, baseUrl, isRemoteSpec, headers, timeout);
+        }
+        console.log('All external references resolved successfully');
+    }
+    /**
+     * Find all external $ref values in the spec
+     */
+    findExternalRefs(obj, refs = []) {
+        if (typeof obj !== 'object' || obj === null) {
+            return refs;
+        }
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                this.findExternalRefs(item, refs);
+            }
+            return refs;
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === '$ref' && typeof value === 'string') {
+                // Check if it's an external reference (contains a file path)
+                if (this.isExternalRef(value)) {
+                    // Remove the fragment (#/...) part if present
+                    const refPath = value.split('#')[0];
+                    if (refPath && !refs.includes(refPath)) {
+                        refs.push(refPath);
+                    }
+                }
+            }
+            else {
+                this.findExternalRefs(value, refs);
+            }
+        }
+        return refs;
+    }
+    /**
+     * Check if a $ref is external (references another file)
+     */
+    isExternalRef(ref) {
+        // External refs start with ./ or ../ or / or http:// or https://
+        return (ref.startsWith('./') ||
+            ref.startsWith('../') ||
+            ref.startsWith('http://') ||
+            ref.startsWith('https://') ||
+            (ref.startsWith('/') && !ref.startsWith('/#')));
+    }
+    /**
+     * Download a single reference file
+     */
+    async downloadReference(ref, specDir, baseUrl, isRemoteSpec, headers, timeout) {
+        // Skip if already downloaded
+        if (this.downloadedRefs.has(ref)) {
+            return;
+        }
+        this.downloadedRefs.add(ref);
+        let refUrl;
+        let outputPath;
+        if (isRemoteSpec && baseUrl) {
+            // For remote specs, construct the full URL
+            refUrl = new URL(ref, baseUrl).toString();
+            // Preserve the directory structure in the output
+            const refPath = ref.split('#')[0];
+            outputPath = path.join(specDir, refPath);
+        }
+        else {
+            // For local specs, resolve relative to the spec directory
+            refUrl = ref;
+            outputPath = path.resolve(specDir, ref.split('#')[0]);
+        }
+        console.log(`  - Downloading reference: ${ref}`);
+        try {
+            // Ensure output directory exists
+            const outputDir = path.dirname(outputPath);
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            if (this.isLocalFile(refUrl) && !isRemoteSpec) {
+                // Copy local file
+                const sourcePath = path.resolve(specDir, refUrl.split('#')[0]);
+                if (fs.existsSync(sourcePath)) {
+                    const content = fs.readFileSync(sourcePath, 'utf-8');
+                    fs.writeFileSync(outputPath, content, 'utf-8');
+                    console.log(`    ✓ Copied: ${sourcePath} -> ${outputPath}`);
+                    // Recursively resolve references in the downloaded file
+                    await this.resolveExternalRefs(outputPath, headers, timeout, path.dirname(sourcePath));
+                }
+                else {
+                    console.warn(`    ⚠ Reference file not found: ${sourcePath}`);
+                }
+            }
+            else {
+                // Download from HTTP/HTTPS
+                const response = await axios_1.default.get(refUrl, {
+                    headers,
+                    timeout: timeout || 30000,
+                    responseType: 'text',
+                });
+                let content = response.data;
+                if (typeof content !== 'string') {
+                    content = JSON.stringify(content, null, 2);
+                }
+                fs.writeFileSync(outputPath, content, 'utf-8');
+                console.log(`    ✓ Downloaded: ${refUrl}`);
+                // Recursively resolve references in the downloaded file
+                const refBaseUrl = this.getBaseUrl(refUrl);
+                await this.resolveExternalRefs(outputPath, headers, timeout, refBaseUrl);
+            }
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                console.error(`    ✗ Failed to download ${ref}: ${error.message}`);
+            }
+            else {
+                console.error(`    ✗ Failed to process ${ref}:`, error);
+            }
+            // Continue with other references even if one fails
+        }
+    }
 }
 exports.SpecDownloader = SpecDownloader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,8 +26,10 @@
   "license": "MIT",
   "dependencies": {
     "axios": "^1.6.0",
+    "class-transformer": "^0.5.1",
     "commander": "^11.0.0",
-    "openapi-class-transformer": "1.0.8"
+    "openapi-class-transformer": "^1.0.11",
+    "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",

package/test-discriminated-output/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md