klasik 1.0.13 → 1.0.16

package/README.md

@@ -6,6 +6,7 @@ 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
+- 📄 **JSON and YAML support** - Automatically parse and handle both formats
 - 🔐 **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
@@ -27,17 +28,23 @@ npm install klasik
 Generate a TypeScript client from a remote OpenAPI spec:
 
 ```bash
+# JSON spec
 npx klasik generate \
   --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json \
   --output ./k8s-client
+
+# YAML spec
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./client
 ```
 
-Generate from a local OpenAPI spec file:
+Generate from a local OpenAPI spec file (JSON or YAML):
 
 ```bash
 # Absolute path
 npx klasik generate \
-  --url /path/to/openapi.json \
+  --url /path/to/openapi.yaml \
   --output ./client
 
 # Relative path
@@ -47,16 +54,22 @@ npx klasik generate \
 
 # file:// URL
 npx klasik generate \
-  --url file:///path/to/openapi.json \
+  --url file:///path/to/openapi.yaml \
   --output ./client
 ```
 
-Download an OpenAPI spec without generating:
+Download an OpenAPI spec without generating (supports JSON and YAML):
 
 ```bash
+# Download JSON spec
 npx klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json
+
+# Download YAML spec
+npx klasik download \
+  --url https://api.example.com/openapi.yaml \
+  --output ./specs/api-spec.yaml
 ```
 
 ### Programmatic Usage
@@ -321,6 +334,8 @@ output/
 ### Supported Reference Types
 
 - **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
+  - When the main spec is from a remote URL, relative paths are resolved against the spec's URL
+  - Example: spec at `https://raw.githubusercontent.com/org/repo/main/api/openapi.yaml` with ref `./schemas/user.yaml` resolves to `https://raw.githubusercontent.com/org/repo/main/api/schemas/user.yaml`
 - **Remote URLs**: `https://api.example.com/schemas/user.yaml`
 - **Mixed**: Main spec from HTTPS, references can be relative or absolute
 

package/USAGE_EXAMPLES.md

@@ -1,5 +1,66 @@
 # Klasik Usage Examples
 
+## JSON and YAML Support
+
+Klasik automatically detects and parses both JSON and YAML OpenAPI specifications. The original format is preserved when downloading.
+
+### CLI Examples
+
+```bash
+# JSON spec
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client
+
+# YAML spec
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./client
+
+# Local YAML file
+npx klasik generate \
+  --url ./specs/openapi.yaml \
+  --output ./client
+
+# Download and keep YAML format
+npx klasik download \
+  --url https://api.example.com/openapi.yaml \
+  --output ./specs/api-spec.yaml \
+  --resolve-refs
+```
+
+### Programmatic Examples
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+// Works with both JSON and YAML
+await new K8sClientGenerator().generate({
+  specUrl: 'https://api.example.com/openapi.yaml',
+  outputDir: './client'
+});
+```
+
+### Mixed Formats with References
+
+Klasik handles specs where the main file is in one format and referenced files are in another:
+
+```yaml
+# openapi.yaml (main spec in YAML)
+openapi: 3.0.0
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: './schemas/users.json#/components/schemas/User'  # JSON reference
+```
+
+Both formats work seamlessly together!
+
 ## Using Custom Headers (Authorization)
 
 ### CLI Example - Authorization Token

package/dist/spec-downloader.d.ts

@@ -54,7 +54,7 @@ export declare class SpecDownloader {
      */
     private generateTempPath;
     /**
-     * Validate that the downloaded content is an OpenAPI spec
+     * Validate that the parsed content is an OpenAPI spec
      */
     private validateSpec;
     /**
@@ -62,7 +62,7 @@ export declare class SpecDownloader {
      */
     cleanupTemp(): void;
     /**
-     * Get base URL from a full URL (removes the filename)
+     * Get base URL from a full URL (removes the filename and ensures trailing slash)
      */
     private getBaseUrl;
     /**

package/dist/spec-downloader.js

@@ -40,6 +40,7 @@ exports.SpecDownloader = void 0;
 const axios_1 = __importDefault(require("axios"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
 class SpecDownloader {
     constructor() {
         this.downloadedRefs = new Set();
@@ -78,22 +79,31 @@ class SpecDownloader {
             }
             // Parse and validate the spec
             let specContent;
+            let parsedSpec;
             if (typeof response.data === 'string') {
-                // Try to parse as JSON to validate
+                // Try to parse as JSON first
                 try {
-                    const parsed = JSON.parse(response.data);
-                    specContent = JSON.stringify(parsed, null, 2);
+                    parsedSpec = JSON.parse(response.data);
+                    specContent = JSON.stringify(parsedSpec, null, 2);
                 }
                 catch {
-                    // If not JSON, might be YAML - save as-is
-                    specContent = response.data;
+                    // If not JSON, try YAML
+                    try {
+                        parsedSpec = yaml.load(response.data);
+                        // Keep YAML format if input was YAML
+                        specContent = response.data;
+                    }
+                    catch {
+                        throw new Error('Failed to parse spec: not valid JSON or YAML');
+                    }
                 }
             }
             else {
+                parsedSpec = response.data;
                 specContent = JSON.stringify(response.data, null, 2);
             }
             // Validate it's an OpenAPI spec
-            this.validateSpec(specContent);
+            this.validateSpec(parsedSpec);
             // Write to file
             fs.writeFileSync(specPath, specContent, 'utf-8');
             console.log(`OpenAPI spec downloaded successfully to ${specPath}`);
@@ -154,24 +164,29 @@ class SpecDownloader {
         }
         // Read the file
         const content = fs.readFileSync(resolvedPath, 'utf-8');
+        // Parse the content (JSON or YAML)
+        let parsedSpec;
+        try {
+            parsedSpec = JSON.parse(content);
+        }
+        catch {
+            try {
+                parsedSpec = yaml.load(content);
+            }
+            catch {
+                throw new Error(`Failed to parse spec at ${resolvedPath}: not valid JSON or YAML`);
+            }
+        }
         // Validate it's an OpenAPI spec
-        this.validateSpec(content);
+        this.validateSpec(parsedSpec);
         // If outputPath is provided, copy to that location
         if (outputPath) {
             const dir = path.dirname(outputPath);
             if (!fs.existsSync(dir)) {
                 fs.mkdirSync(dir, { recursive: true });
             }
-            // Parse and format if it's JSON
-            let formattedContent = content;
-            try {
-                const parsed = JSON.parse(content);
-                formattedContent = JSON.stringify(parsed, null, 2);
-            }
-            catch {
-                // Not JSON, keep original
-            }
-            fs.writeFileSync(outputPath, formattedContent, 'utf-8');
+            // Keep the original format (JSON or YAML)
+            fs.writeFileSync(outputPath, content, 'utf-8');
             console.log(`OpenAPI spec copied to ${outputPath}`);
             return outputPath;
         }
@@ -189,28 +204,22 @@ class SpecDownloader {
         return path.join(process.cwd(), '.tmp', filename);
     }
     /**
-     * Validate that the downloaded content is an OpenAPI spec
+     * Validate that the parsed content is an OpenAPI spec
      */
-    validateSpec(content) {
-        try {
-            const spec = JSON.parse(content);
-            // Check for OpenAPI version
-            if (!spec.openapi && !spec.swagger) {
-                throw new Error('Invalid OpenAPI spec: missing "openapi" or "swagger" field');
-            }
-            // Check for required fields
-            if (!spec.info) {
-                throw new Error('Invalid OpenAPI spec: missing "info" field');
-            }
-            if (!spec.paths && !spec.components) {
-                throw new Error('Invalid OpenAPI spec: must have either "paths" or "components"');
-            }
+    validateSpec(spec) {
+        if (!spec || typeof spec !== 'object') {
+            throw new Error('Invalid OpenAPI spec: not a valid object');
         }
-        catch (error) {
-            if (error instanceof SyntaxError) {
-                throw new Error('Invalid OpenAPI spec: not valid JSON');
-            }
-            throw error;
+        // Check for OpenAPI version
+        if (!spec.openapi && !spec.swagger) {
+            throw new Error('Invalid OpenAPI spec: missing "openapi" or "swagger" field');
+        }
+        // Check for required fields
+        if (!spec.info) {
+            throw new Error('Invalid OpenAPI spec: missing "info" field');
+        }
+        if (!spec.paths && !spec.components) {
+            throw new Error('Invalid OpenAPI spec: must have either "paths" or "components"');
         }
     }
     /**
@@ -224,14 +233,16 @@ class SpecDownloader {
         }
     }
     /**
-     * Get base URL from a full URL (removes the filename)
+     * Get base URL from a full URL (removes the filename and ensures trailing slash)
      */
     getBaseUrl(url) {
         try {
             const urlObj = new URL(url);
             const pathParts = urlObj.pathname.split('/');
             pathParts.pop(); // Remove filename
-            urlObj.pathname = pathParts.join('/');
+            // Ensure the path ends with a slash for proper relative URL resolution
+            const basePath = pathParts.join('/');
+            urlObj.pathname = basePath.endsWith('/') ? basePath : basePath + '/';
             return urlObj.toString();
         }
         catch {
@@ -250,8 +261,13 @@ class SpecDownloader {
             spec = JSON.parse(content);
         }
         catch {
-            console.log('Spec is not JSON, skipping reference resolution');
-            return;
+            try {
+                spec = yaml.load(content);
+            }
+            catch {
+                console.log('Spec is not valid JSON or YAML, skipping reference resolution');
+                return;
+            }
         }
         const refs = this.findExternalRefs(spec);
         if (refs.length === 0) {
@@ -331,6 +347,10 @@ class SpecDownloader {
             outputPath = path.resolve(specDir, ref.split('#')[0]);
         }
         console.log(`  - Downloading reference: ${ref}`);
+        if (isRemoteSpec && baseUrl) {
+            console.log(`    Base URL: ${baseUrl}`);
+            console.log(`    Resolved to: ${refUrl}`);
+        }
         try {
             // Ensure output directory exists
             const outputDir = path.dirname(outputPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.13",
+  "version": "1.0.16",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,11 +28,13 @@
     "axios": "^1.6.0",
     "class-transformer": "^0.5.1",
     "commander": "^11.0.0",
+    "js-yaml": "^4.1.0",
     "openapi-class-transformer": "^1.0.11",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.0.0",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",