klasik 1.0.20 → 1.0.22

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "WebSearch",
+      "Bash(npx @openapitools/openapi-generator-cli help generate:*)",
+      "Bash(node dist/cli.js generate:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm install:*)",
+      "WebFetch(domain:dev.to)",
+      "WebFetch(domain:saintlouvent.com)",
+      "WebFetch(domain:zod.dev)",
+      "Bash(node test-disc-union.js:*)",
+      "Bash(node test-disc-code.js:*)",
+      "Bash(node test-new-validators.js:*)"
+    ]
+  }
+}

package/README.md

@@ -104,6 +104,14 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
   - Perfect for authorization: `--header "Authorization: Bearer token"`
 - `-r, --resolve-refs` - Resolve and download external `$ref` references
 - `--esm` - Add `.js` extensions to imports for ESM compatibility (Node.js modules)
+- `--nestjs-swagger` - Include NestJS Swagger `@ApiProperty` decorators in generated models
+  - Automatically adds `@nestjs/swagger` to generated package.json
+  - Ideal for NestJS applications with Swagger/OpenAPI documentation
+  - Works with both `full` and `models-only` generation modes
+- `--class-validator` - Include class-validator decorators for runtime validation (requires openapi-class-transformer v2.0+)
+  - Automatically adds `class-validator` and `class-transformer` to generated package.json
+  - Enables runtime validation with decorators like `@IsString`, `@IsEmail`, `@Min`, `@Max`
+  - Forward-compatible flag - full decorator generation coming in future version
 - `-t, --template <dir>` - Custom template directory (klasik includes enhanced TSDoc templates by default)
 - `-k, --keep-spec` - Keep the downloaded spec file after generation
 - `--timeout <ms>` - Request timeout in milliseconds for HTTP requests (default: 30000)
@@ -125,6 +133,28 @@ klasik generate \
   --header "Authorization: Bearer token123" \
   --resolve-refs
 
+# NestJS integration with Swagger decorators
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated \
+  --mode models-only \
+  --nestjs-swagger
+
+# With runtime validation decorators
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated \
+  --mode models-only \
+  --class-validator
+
+# Full NestJS setup: Swagger docs + validation
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated \
+  --mode models-only \
+  --nestjs-swagger \
+  --class-validator
+
 # Multiple headers
 klasik generate \
   --url https://api.example.com/openapi.json \
@@ -183,11 +213,14 @@ const generator = new K8sClientGenerator();
 await generator.generate({
   specUrl: 'https://api.example.com/openapi.json',
   outputDir: './client',
+  mode: 'models-only',
   headers: {
     'Authorization': 'Bearer token123',
     'X-Custom-Header': 'value'
   },
   resolveReferences: true, // Download external $ref files
+  nestJsSwagger: true, // Include @ApiProperty decorators
+  classValidator: true, // Include validation decorators
   templateDir: './custom-templates', // Optional
   keepSpec: true, // Keep downloaded spec file
   timeout: 60000 // Request timeout in ms
@@ -229,6 +262,8 @@ The generated TypeScript client includes:
 - ✅ **Vendor extensions** - Preserved in JSDoc comments and metadata
 - ✅ **Error handling** - Configurable transformation error handlers
 - ✅ **Configuration options** - Enable/disable transformation, custom error handlers
+- ✅ **NestJS Swagger decorators** (optional) - `@ApiProperty` with type, description, example, required, and nullable when `--nestjs-swagger` is enabled
+- ✅ **class-validator decorators** (optional) - Runtime validation decorators when `--class-validator` is enabled (full support in v2.0+)
 
 ### Enhanced TSDoc Documentation
 
@@ -422,6 +457,167 @@ await new K8sClientGenerator().generate({
 });
 ```
 
+## NestJS Integration
+
+### Using with NestJS Applications
+
+Klasik-generated models integrate seamlessly with NestJS applications. Use `--mode models-only` with decorator flags for best results.
+
+#### Swagger Documentation Support
+
+Generate models with `@ApiProperty` decorators for automatic Swagger documentation:
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated/dto \
+  --mode models-only \
+  --nestjs-swagger
+```
+
+This generates DTOs like:
+
+```typescript
+import { Expose } from 'class-transformer';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class UserDto {
+    @ApiProperty({
+        type: String,
+        description: 'Unique identifier',
+        required: true,
+        example: '123e4567-e89b-41d3-a456-426614174000',
+    })
+    @Expose()
+    id: string;
+
+    @ApiProperty({
+        type: String,
+        description: 'User email address',
+        required: true,
+        format: 'email',
+    })
+    @Expose()
+    email: string;
+}
+```
+
+Use in your NestJS controllers:
+
+```typescript
+import { Controller, Get, Post, Body } from '@nestjs/common';
+import { ApiTags, ApiResponse } from '@nestjs/swagger';
+import { UserDto } from './generated/dto';
+
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  @Get()
+  @ApiResponse({ type: [UserDto], status: 200 })
+  async findAll(): Promise<UserDto[]> {
+    // Your implementation
+  }
+
+  @Post()
+  @ApiResponse({ type: UserDto, status: 201 })
+  async create(@Body() createUserDto: UserDto): Promise<UserDto> {
+    // Your implementation
+  }
+}
+```
+
+Your Swagger UI automatically displays complete documentation from the `@ApiProperty` decorators.
+
+#### Runtime Validation Support
+
+Add the `--class-validator` flag for runtime validation decorators:
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated/dto \
+  --mode models-only \
+  --nestjs-swagger \
+  --class-validator
+```
+
+**Note**: Full decorator generation requires openapi-class-transformer v2.0+. For now, the dependencies are added to package.json, and you can manually add validation decorators:
+
+```typescript
+import { Expose } from 'class-transformer';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsEmail } from 'class-validator';
+
+export class UserDto {
+    @ApiProperty({ type: String, required: true })
+    @IsString()
+    @Expose()
+    id: string;
+
+    @ApiProperty({ type: String, required: true, format: 'email' })
+    @IsEmail()
+    @Expose()
+    email: string;
+}
+```
+
+Use with NestJS ValidationPipe:
+
+```typescript
+import { ValidationPipe } from '@nestjs/common';
+
+// In main.ts
+app.useGlobalPipes(new ValidationPipe({
+  transform: true,
+  whitelist: true,
+}));
+
+// In controller
+@Post()
+async create(@Body() dto: UserDto): Promise<UserDto> {
+  // dto is already validated and transformed to UserDto instance!
+}
+```
+
+#### Required Dependencies for NestJS
+
+When using `--nestjs-swagger` or `--class-validator`, ensure your project has these peer dependencies:
+
+```bash
+npm install @nestjs/swagger swagger-ui-express
+npm install class-validator class-transformer
+npm install reflect-metadata
+```
+
+Update your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+#### Best Practices
+
+1. **Use models-only mode**: Generate only DTOs, keep your NestJS business logic separate
+2. **Separate directories**: Generate into `src/generated/dto` or similar
+3. **Extend generated classes**: For complex validation, extend generated DTOs
+4. **Version control**: Commit generated files or regenerate in CI/CD
+
+```typescript
+// Custom DTO extending generated model
+import { UserDto } from '../generated/dto';
+import { IsStrongPassword } from 'class-validator';
+
+export class CreateUserDto extends UserDto {
+  @IsStrongPassword()
+  password: string;
+}
+```
+
 ## Best Practices for Existing Projects
 
 When integrating klasik into an existing TypeScript project, follow these best practices to avoid conflicts:

package/dist/cli.js

@@ -53,6 +53,8 @@ program
     .option('-k, --keep-spec', 'Keep the downloaded spec file after generation', false)
     .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
     .option('--esm', 'Add .js extensions to imports for ESM compatibility', false)
+    .option('--nestjs-swagger', 'Include NestJS Swagger @ApiProperty decorators in generated models', false)
+    .option('--class-validator', 'Include class-validator decorators in generated models', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -84,6 +86,8 @@ program
             keepSpec: options.keepSpec,
             resolveReferences: options.resolveRefs,
             fixEsmImports: options.esm,
+            nestJsSwagger: options.nestjsSwagger,
+            classValidator: options.classValidator,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);

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

@@ -38,6 +38,27 @@ export interface K8sClientGeneratorOptions {
      * @default false
      */
     fixEsmImports?: boolean;
+    /**
+     * Include NestJS Swagger @ApiProperty decorators in generated models
+     * Adds @nestjs/swagger to generated package.json
+     * @default false
+     */
+    nestJsSwagger?: boolean;
+    /**
+     * Include class-validator decorators in generated models
+     * Adds class-validator to generated package.json
+     * Decorators include: @IsString, @IsNumber, @IsOptional, @Min, @Max, @IsEmail, etc.
+     * Note: Full decorator generation requires openapi-class-transformer v2.0+
+     * @default false
+     */
+    classValidator?: boolean;
+    /**
+     * Skip adding .js extensions to imports/exports
+     * Useful for bundlers like webpack/Next.js that don't want file extensions
+     * When true, imports will be: import { Foo } from './foo' instead of './foo.js'
+     * @default false
+     */
+    skipJsExtensions?: boolean;
     /**
      * Request timeout for downloading spec in milliseconds
      * @default 30000
@@ -64,4 +85,8 @@ export declare class K8sClientGenerator {
      * Clean up the downloaded spec file
      */
     private cleanupSpecFile;
+    /**
+     * Add decorator dependencies to generated package.json
+     */
+    private addDecoratorDependencies;
 }

package/dist/k8s-client-generator.js

@@ -48,7 +48,7 @@ class K8sClientGenerator {
      * Generate TypeScript client from a remote OpenAPI spec URL
      */
     async generate(options) {
-        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, fixEsmImports = false, timeout, } = options;
+        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, fixEsmImports = false, nestJsSwagger = false, classValidator = false, skipJsExtensions = false, timeout, } = options;
         let specPath;
         try {
             // Step 1: Download the OpenAPI spec
@@ -74,6 +74,8 @@ class K8sClientGenerator {
                 inputSpec: jsonSpecPath,
                 outputDir,
                 modelsOnly: mode === 'models-only',
+                nestJsSwagger,
+                skipJsExtensions,
             };
             // Only add templateDir if it's provided
             if (templateDir) {
@@ -81,6 +83,11 @@ class K8sClientGenerator {
             }
             const generator = new openapi_class_transformer_1.Generator(generatorOptions);
             await generator.generate();
+            // Step 3.5: Update generated package.json with decorator dependencies
+            if (nestJsSwagger || classValidator) {
+                console.log('Step 3.5: Adding decorator dependencies to package.json...');
+                this.addDecoratorDependencies(outputDir, nestJsSwagger, classValidator);
+            }
             // Step 4: Fix ESM imports if requested
             if (fixEsmImports) {
                 console.log('Step 4: Fixing ESM imports...');
@@ -172,5 +179,42 @@ class K8sClientGenerator {
             console.warn('Warning: Failed to cleanup spec file:', error);
         }
     }
+    /**
+     * Add decorator dependencies to generated package.json
+     */
+    addDecoratorDependencies(outputDir, nestJsSwagger, classValidator) {
+        const packageJsonPath = path.join(outputDir, 'package.json');
+        if (!fs.existsSync(packageJsonPath)) {
+            console.warn('Warning: package.json not found in output directory');
+            console.log('Tip: In models-only mode, add these dependencies to your project manually');
+            return;
+        }
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            // Initialize dependencies if missing
+            if (!packageJson.dependencies) {
+                packageJson.dependencies = {};
+            }
+            // Add @nestjs/swagger if enabled
+            if (nestJsSwagger) {
+                packageJson.dependencies['@nestjs/swagger'] = '^7.0.0';
+                console.log('  ✓ Added @nestjs/swagger@^7.0.0 to dependencies');
+            }
+            // Add class-validator if enabled
+            if (classValidator) {
+                packageJson.dependencies['class-validator'] = '^0.14.0';
+                packageJson.dependencies['class-transformer'] = '^0.5.1'; // Required peer dependency
+                console.log('  ✓ Added class-validator@^0.14.0 to dependencies');
+                console.log('  ✓ Added class-transformer@^0.5.1 to dependencies');
+                console.log('  Note: Full decorator generation requires openapi-class-transformer v2.0+');
+                console.log('        For now, you can manually add validation decorators to the generated models');
+            }
+            // Write back with formatting
+            fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+        }
+        catch (error) {
+            console.warn('Warning: Failed to update package.json:', error);
+        }
+    }
 }
 exports.K8sClientGenerator = K8sClientGenerator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,14 +22,18 @@
     "api-client",
     "generator"
   ],
-  "author": "",
+  "author": "hisco",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hisco/klasik.git"
+  },
   "license": "MIT",
   "dependencies": {
     "axios": "^1.6.0",
     "class-transformer": "^0.5.1",
     "commander": "^11.0.0",
     "js-yaml": "^4.1.0",
-    "openapi-class-transformer": "^1.0.11",
+    "openapi-class-transformer": "^1.0.13",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {

package/{test-discriminated-output/configuration.ts → templates/configuration.mustache}

@@ -1,17 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
- * Test API with Discriminated Unions
- * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
- *
- * The version of the OpenAPI document: 1.0.0
- * 
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-
+{{>licenseInfo}}
 
 export interface ConfigurationParameters {
     apiKey?: string | Promise<string> | ((name: string) => string) | ((name: string) => Promise<string>);
@@ -127,6 +116,9 @@ export class Configuration {
         this.baseOptions = {
             ...param.baseOptions,
             headers: {
+                {{#httpUserAgent}}
+                'User-Agent': "{{httpUserAgent}}",
+                {{/httpUserAgent}}
                 ...param.baseOptions?.headers,
             },
         };

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

@@ -1,23 +0,0 @@
-# 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

package/test-discriminated-output/api/default-api.ts

@@ -1,142 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Test API with Discriminated Unions
- * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
- *
- * The version of the OpenAPI document: 1.0.0
- * 
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-
-
-import type { Configuration } from '../configuration.js';
-import type { AxiosPromise, AxiosInstance, RawAxiosRequestConfig } from 'axios';
-import globalAxios, { type AxiosResponse } from 'axios';
-import { plainToInstance } from 'class-transformer';
-// URLSearchParams not necessarily used
-// @ts-ignore
-import { URL, URLSearchParams } from 'url';
-// Some imports not used depending on template conditions
-// @ts-ignore
-import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, createRequestFunction } from '../common.js';
-// @ts-ignore
-import { BASE_PATH, COLLECTION_FORMATS, type RequestArgs, BaseAPI, RequiredError, operationServerMap } from '../base.js';
-// @ts-ignore
-import { Capability } from '../models/index.js';
-/**
- * DefaultApi - axios parameter creator
- * @export
- */
-export const DefaultApiAxiosParamCreator = function (configuration?: Configuration) {
-    return {
-        /**
-         * 
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        getCapabilities: async (options: RawAxiosRequestConfig = {}): Promise<RequestArgs> => {
-            const localVarPath = `/capabilities`;
-            // use dummy base URL string because the URL constructor only accepts absolute URLs.
-            const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL);
-            let baseOptions;
-            if (configuration) {
-                baseOptions = configuration.baseOptions;
-            }
-
-            const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options};
-            const localVarHeaderParameter = {} as any;
-            const localVarQueryParameter = {} as any;
-
-
-    
-            setSearchParams(localVarUrlObj, localVarQueryParameter);
-            let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
-            localVarRequestOptions.headers = {...localVarHeaderParameter, ...headersFromBaseOptions, ...options.headers};
-
-            return {
-                url: toPathString(localVarUrlObj),
-                options: localVarRequestOptions,
-            };
-        },
-    }
-};
-
-/**
- * DefaultApi - functional programming interface
- * @export
- */
-export const DefaultApiFp = function(configuration?: Configuration) {
-    const localVarAxiosParamCreator = DefaultApiAxiosParamCreator(configuration)
-    return {
-        /**
-         * 
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        async getCapabilities(options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<Array<Capability>>> {
-            const localVarAxiosArgs = await localVarAxiosParamCreator.getCapabilities(options);
-            const localVarOperationServerIndex = configuration?.serverIndex ?? 0;
-            const localVarOperationServerBasePath = operationServerMap['DefaultApi.getCapabilities']?.[localVarOperationServerIndex]?.url;
-            return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath).then(response => {
-                // Check if response transformation is enabled (default: true)
-                if (configuration?.enableResponseTransformation !== false) {
-                    try {
-                        response.data = plainToInstance(Capability, response.data as any[]);
-                    } catch (error) {
-                        // Handle transformation errors
-                        if (configuration?.onTransformationError) {
-                            configuration.onTransformationError(error as Error, Capability, response.data);
-                        } else {
-                            console.error('class-transformer failed to transform response:', error);
-                            console.error('Returning original response data. To handle this error, provide onTransformationError in Configuration.');
-                        }
-                        // Return original data on error (cast for type safety)
-                        response.data = response.data as any as Capability[];
-                    }
-                }
-                return response as AxiosResponse<Capability[]>;
-            });
-        },
-    }
-};
-
-/**
- * DefaultApi - factory interface
- * @export
- */
-export const DefaultApiFactory = function (configuration?: Configuration, basePath?: string, axios?: AxiosInstance) {
-    const localVarFp = DefaultApiFp(configuration)
-    return {
-        /**
-         * 
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        getCapabilities(options?: RawAxiosRequestConfig): AxiosPromise<Array<Capability>> {
-            return localVarFp.getCapabilities(options).then((request) => request(axios, basePath));
-        },
-    };
-};
-
-/**
- * DefaultApi - object-oriented interface
- * @export
- * @class DefaultApi
- * @extends {BaseAPI}
- */
-export class DefaultApi extends BaseAPI {
-    /**
-     * 
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     * @memberof DefaultApi
-     */
-    public getCapabilities(options?: RawAxiosRequestConfig) {
-        return DefaultApiFp(this.configuration).getCapabilities(options).then((request) => request(this.axios, this.basePath));
-    }
-}
-

package/test-discriminated-output/api.ts

@@ -1,19 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Test API with Discriminated Unions
- * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
- *
- * The version of the OpenAPI document: 1.0.0
- * 
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-
-
-
-export { Configuration } from './configuration.js';
-export * from './api/default-api.js';
-