zod-codegen 1.1.2 → 1.2.1

package/.github/workflows/ci.yml

@@ -29,25 +29,25 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          cache: 'yarn'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Run type check
-        run: npm run type-check
+        run: yarn type-check
 
       - name: Run linter
-        run: npm run lint:check
+        run: yarn lint:check
 
       - name: Run formatter check
-        run: npm run format:check
+        run: yarn format:check
 
       - name: Build project
-        run: npm run build
+        run: yarn build
 
       - name: Run tests
-        run: npm run test:coverage
+        run: yarn test:coverage
 
       - name: Upload coverage to Codecov
         if: matrix.node-version == '24.11.1' && matrix.os == 'ubuntu-latest'
@@ -70,13 +70,13 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: '24.11.1'
-          cache: 'npm'
+          cache: 'yarn'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Run security audit
-        run: npm audit --audit-level high
+        run: yarn audit --level high
 
   build:
     name: Build & Package
@@ -91,13 +91,13 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: '24.11.1'
-          cache: 'npm'
+          cache: 'yarn'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Build project
-        run: npm run build
+        run: yarn build
 
       - name: Test CLI
         run: |
@@ -129,15 +129,15 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: '24.11.1'
-          cache: 'npm'
+          cache: 'yarn'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Build project
-        run: npm run build
+        run: yarn build
 
       - name: Preview semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: npm run release:dry
+        run: yarn release:dry

package/.github/workflows/release.yml

@@ -29,26 +29,26 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: '24.11.1'
-          cache: 'npm'
+          cache: 'yarn'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Run type check
-        run: npm run type-check
+        run: yarn type-check
 
       - name: Run linter check
-        run: npm run lint:check
+        run: yarn lint:check
 
       - name: Run formatter check
-        run: npm run format:check
+        run: yarn format:check
 
       - name: Run tests with coverage
-        run: npm run test:coverage
+        run: yarn test:coverage
 
       - name: Build project
-        run: npm run build
+        run: yarn build
 
       - name: Test CLI functionality
         run: |
@@ -62,4 +62,4 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npx semantic-release
+        run: yarn release

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## <small>1.2.1 (2025-11-19)</small>
+
+- Merge pull request #33 from julienandreu/fix/add-z-infer-to-response-types ([a14d81c](https://github.com/julienandreu/zod-codegen/commit/a14d81c)), closes [#33](https://github.com/julienandreu/zod-codegen/issues/33)
+- fix: add z.infer to response types in generated methods ([c45ac77](https://github.com/julienandreu/zod-codegen/commit/c45ac77))
+
+## 1.2.0 (2025-11-19)
+
+- Merge pull request #31 from julienandreu/dependabot/npm_and_yarn/dev-dependencies-1dd8918b9f ([97ebb65](https://github.com/julienandreu/zod-codegen/commit/97ebb65)), closes [#31](https://github.com/julienandreu/zod-codegen/issues/31)
+- Merge pull request #32 from julienandreu/feat/add-jsdoc-comments ([9e0d589](https://github.com/julienandreu/zod-codegen/commit/9e0d589)), closes [#32](https://github.com/julienandreu/zod-codegen/issues/32)
+- feat: add JSDoc comments to generated API client methods ([4f42f97](https://github.com/julienandreu/zod-codegen/commit/4f42f97))
+- chore(deps-dev): bump the dev-dependencies group with 3 updates ([43be1ab](https://github.com/julienandreu/zod-codegen/commit/43be1ab))
+
 ## <small>1.1.2 (2025-11-13)</small>
 
 - Merge pull request #30 from julienandreu/fix/cli-strict-mode ([d098ac7](https://github.com/julienandreu/zod-codegen/commit/d098ac7)), closes [#30](https://github.com/julienandreu/zod-codegen/issues/30)

package/CONTRIBUTING.md

@@ -22,7 +22,7 @@ This project adheres to a code of conduct. By participating, you are expected to
 ### Prerequisites
 
 - Node.js >= 24.11.1
-- npm or yarn
+- yarn
 - Git
 
 ### Development Setup
@@ -37,24 +37,24 @@ This project adheres to a code of conduct. By participating, you are expected to
 2. **Install Dependencies**
 
    ```bash
-   npm install
+   yarn install
    ```
 
 3. **Build the Project**
 
    ```bash
-   npm run build
+   yarn build
    ```
 
 4. **Run Tests**
 
    ```bash
-   npm test
+   yarn test
    ```
 
 5. **Run Development Mode**
    ```bash
-   npm run dev
+   yarn dev
    ```
 
 ## Making Changes
@@ -119,7 +119,7 @@ test: add integration tests for CLI
 3. **Validate Your Changes**
 
    ```bash
-   npm run validate
+   yarn validate
    ```
 
    This runs:
@@ -171,10 +171,10 @@ We use ESLint and Prettier for consistent code style:
 
 ```bash
 # Auto-fix linting issues
-npm run lint
+yarn lint
 
 # Format code
-npm run format
+yarn format
 ```
 
 ### File Structure
@@ -218,16 +218,16 @@ tests/
 
 ```bash
 # Run all tests
-npm test
+yarn test
 
 # Run tests in watch mode
-npm run test:watch
+yarn test:watch
 
 # Run with coverage
-npm run test:coverage
+yarn test:coverage
 
 # Run specific test file
-npx vitest run generator.test.ts
+yarn vitest run generator.test.ts
 ```
 
 ## Documentation

package/PERFORMANCE.md

@@ -12,14 +12,14 @@ For even faster builds, you can optionally use the TypeScript Native Preview (TS
 ### Installation
 
 ```bash
-npm install -D @typescript/native-preview
+yarn add -D @typescript/native-preview
 ```
 
 ### Usage
 
 ```bash
 # Use native compiler for builds
-npm run build:native
+yarn build:native
 
 # Or use directly
 npx tsgo --project tsconfig.json
@@ -52,8 +52,8 @@ To compare performance:
 
 ```bash
 # Standard TypeScript
-time npm run build
+time yarn build
 
 # Native TypeScript
-time npm run build:native
+time yarn build:native
 ```

package/README.md

@@ -28,13 +28,13 @@ A powerful TypeScript code generator that creates **Zod schemas** and **type-saf
 ### Global Installation (CLI)
 
 ```bash
-npm install -g zod-codegen
+yarn global add zod-codegen
 ```
 
 ### Project Installation
 
 ```bash
-npm install --save-dev zod-codegen
+yarn add --dev zod-codegen
 ```
 
 ## 🔧 Usage
@@ -378,7 +378,7 @@ Each example includes:
 ### Prerequisites
 
 - Node.js ≥ 24.11.1
-- npm or yarn
+- yarn
 
 ### Setup
 
@@ -388,52 +388,52 @@ git clone https://github.com/julienandreu/zod-codegen.git
 cd zod-codegen
 
 # Install dependencies
-npm install
+yarn install
 
 # Build the project
-npm run build
+yarn build
 
 # Run tests
-npm test
+yarn test
 
 # Run linting
-npm run lint
+yarn lint
 
 # Format code
-npm run format
+yarn format
 ```
 
 ### Testing
 
 ```bash
 # Run all tests
-npm test
+yarn test
 
 # Run tests in watch mode
-npm run test:watch
+yarn test:watch
 
 # Run tests with coverage
-npm run test:coverage
+yarn test:coverage
 
 # Run tests with UI
-npm run test:ui
+yarn test:ui
 ```
 
 ### Available Scripts
 
-| Script                  | Description                                     |
-| ----------------------- | ----------------------------------------------- |
-| `npm run build`         | Build the project                               |
-| `npm run build:watch`   | Build in watch mode                             |
-| `npm run dev`           | Development mode with example                   |
-| `npm test`              | Run tests                                       |
-| `npm run test:watch`    | Run tests in watch mode                         |
-| `npm run test:coverage` | Run tests with coverage                         |
-| `npm run lint`          | Lint and fix code                               |
-| `npm run format`        | Format code with Prettier                       |
-| `npm run type-check`    | Type check without emitting                     |
-| `npm run validate`      | Run all checks (lint, format, type-check, test) |
-| `npm run clean`         | Clean build artifacts                           |
+| Script               | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `yarn build`         | Build the project                               |
+| `yarn build:watch`   | Build in watch mode                             |
+| `yarn dev`           | Development mode with example                   |
+| `yarn test`          | Run tests                                       |
+| `yarn test:watch`    | Run tests in watch mode                         |
+| `yarn test:coverage` | Run tests with coverage                         |
+| `yarn lint`          | Lint and fix code                               |
+| `yarn format`        | Format code with Prettier                       |
+| `yarn type-check`    | Type check without emitting                     |
+| `yarn validate`      | Run all checks (lint, format, type-check, test) |
+| `yarn clean`         | Clean build artifacts                           |
 
 ## 📋 Requirements
 
@@ -450,8 +450,8 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 1. Fork the repository
 2. Create your feature branch: `git checkout -b feature/amazing-feature`
 3. Make your changes
-4. Run tests: `npm test`
-5. Run validation: `npm run validate`
+4. Run tests: `yarn test`
+5. Run validation: `yarn validate`
 6. Commit your changes: `git commit -m 'feat: add amazing feature'`
 7. Push to the branch: `git push origin feature/amazing-feature`
 8. Open a Pull Request

package/SECURITY.md

@@ -75,7 +75,7 @@ When using zod-codegen, please follow these security best practices:
 
 - Keep zod-codegen and its dependencies up to date
 - Regularly audit your dependency tree for known vulnerabilities
-- Use tools like `npm audit` to check for security issues
+- Use tools like `yarn audit` or `npm audit` to check for security issues
 
 ## Known Security Considerations
 

package/dist/src/services/code-generator.service.js

@@ -296,7 +296,15 @@ export class TypeScriptCodeGeneratorService {
         else {
             statements.push(ts.factory.createReturnStatement(ts.factory.createAwaitExpression(makeRequestCall)));
         }
-        return ts.factory.createMethodDeclaration([ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)], undefined, ts.factory.createIdentifier(String(schema.operationId)), undefined, undefined, parameters, responseType, ts.factory.createBlock(statements, true));
+        const methodDeclaration = ts.factory.createMethodDeclaration([ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)], undefined, ts.factory.createIdentifier(String(schema.operationId)), undefined, undefined, parameters, responseType, ts.factory.createBlock(statements, true));
+        // Add JSDoc comment if summary or description exists
+        const jsdocComment = this.buildJSDocComment(schema.summary, schema.description, schema, responseType);
+        if (jsdocComment) {
+            // addSyntheticLeadingComment expects the comment content without delimiters
+            // and will wrap it in /** */ for JSDoc-style comments
+            ts.addSyntheticLeadingComment(methodDeclaration, ts.SyntaxKind.MultiLineCommentTrivia, `*\n${jsdocComment}\n `, true);
+        }
+        return methodDeclaration;
     }
     buildPathExpression(path, pathParams) {
         // Replace {param} with ${param} for template literal
@@ -508,9 +516,36 @@ export class TypeScriptCodeGeneratorService {
         }
         const responseSchema = response.content['application/json'].schema;
         const typeName = this.getSchemaTypeName(responseSchema, schemas);
-        return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier('Promise'), [
-            ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined),
-        ]);
+        const inferredType = this.wrapTypeWithZInfer(typeName, schemas);
+        return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier('Promise'), [inferredType]);
+    }
+    wrapTypeWithZInfer(typeName, schemas) {
+        // Primitive types and Record types don't need z.infer
+        const primitiveTypes = ['string', 'number', 'boolean', 'unknown'];
+        if (primitiveTypes.includes(typeName) || typeName.startsWith('Record<')) {
+            return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
+        }
+        // Handle array types like "Pet[]"
+        if (typeName.endsWith('[]')) {
+            const itemTypeName = typeName.slice(0, -2);
+            const sanitizedItemTypeName = this.typeBuilder.sanitizeIdentifier(itemTypeName);
+            // Check if the item type is a custom schema
+            if (schemas[sanitizedItemTypeName]) {
+                // Return z.infer<typeof ItemType>[]
+                const zInferType = ts.factory.createTypeReferenceNode(ts.factory.createQualifiedName(ts.factory.createIdentifier('z'), ts.factory.createIdentifier('infer')), [ts.factory.createTypeQueryNode(ts.factory.createIdentifier(sanitizedItemTypeName), undefined)]);
+                return ts.factory.createArrayTypeNode(zInferType);
+            }
+            // If it's a primitive array, return as-is
+            return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
+        }
+        // Handle custom schema types
+        const sanitizedTypeName = this.typeBuilder.sanitizeIdentifier(typeName);
+        if (schemas[sanitizedTypeName]) {
+            // Return z.infer<typeof TypeName>
+            return ts.factory.createTypeReferenceNode(ts.factory.createQualifiedName(ts.factory.createIdentifier('z'), ts.factory.createIdentifier('infer')), [ts.factory.createTypeQueryNode(ts.factory.createIdentifier(sanitizedTypeName), undefined)]);
+        }
+        // Fallback: return as-is if we can't determine
+        return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
     }
     buildServerConfiguration(openapi) {
         const servers = openapi.servers;
@@ -669,6 +704,75 @@ export class TypeScriptCodeGeneratorService {
         ts.addSyntheticTrailingComment(commentNode, ts.SyntaxKind.SingleLineCommentTrivia, ` ${text}`, true);
         return ts.factory.createExpressionStatement(commentNode);
     }
+    /**
+     * Builds a JSDoc comment string from operation metadata
+     */
+    buildJSDocComment(summary, description, schema, responseType) {
+        const lines = [];
+        // Add summary or description as the main comment
+        if (summary) {
+            lines.push(` * ${summary}`);
+        }
+        else if (description) {
+            // Use first line of description as summary if no summary exists
+            const firstLine = description.split('\n')[0]?.trim();
+            if (firstLine) {
+                lines.push(` * ${firstLine}`);
+            }
+        }
+        // Add full description if it exists and is different from summary
+        if (description && description !== summary) {
+            const descLines = description.split('\n');
+            if (descLines.length > 1 || descLines[0] !== summary) {
+                if (lines.length > 0) {
+                    lines.push(' *');
+                }
+                descLines.forEach((line) => {
+                    lines.push(` * ${line.trim() || ''}`);
+                });
+            }
+        }
+        // Add @param tags for each parameter
+        if (schema.parameters && schema.parameters.length > 0) {
+            if (lines.length > 0) {
+                lines.push(' *');
+            }
+            for (const param of schema.parameters) {
+                const paramName = this.typeBuilder.sanitizeIdentifier(param.name);
+                const paramDesc = param.description ? ` ${param.description}` : '';
+                lines.push(` * @param ${paramName}${paramDesc}`);
+            }
+        }
+        // Add @param tag for request body if present
+        if (schema.requestBody) {
+            const bodyDesc = schema.requestBody.description ? ` ${schema.requestBody.description}` : '';
+            lines.push(` * @param body${bodyDesc}`);
+        }
+        // Add @returns tag if we have a response type
+        if (responseType) {
+            // Extract the inner type from Promise<T> for JSDoc
+            let returnTypeText;
+            if (ts.isTypeReferenceNode(responseType) &&
+                ts.isIdentifier(responseType.typeName) &&
+                responseType.typeName.text === 'Promise' &&
+                responseType.typeArguments &&
+                responseType.typeArguments.length > 0 &&
+                responseType.typeArguments[0]) {
+                // Extract the inner type from Promise<T>
+                const innerType = responseType.typeArguments[0];
+                returnTypeText = this.printer.printNode(ts.EmitHint.Unspecified, innerType, ts.createSourceFile('', '', ts.ScriptTarget.Latest));
+            }
+            else {
+                returnTypeText = this.printer.printNode(ts.EmitHint.Unspecified, responseType, ts.createSourceFile('', '', ts.ScriptTarget.Latest));
+            }
+            lines.push(` * @returns {${returnTypeText}}`);
+        }
+        // Build the complete JSDoc comment (without delimiters, as addSyntheticLeadingComment adds them)
+        if (lines.length === 0) {
+            return '';
+        }
+        return lines.join('\n');
+    }
     buildZodAST(input) {
         const [initial, ...rest] = input;
         const safeInitial = this.ZodAST.safeParse(initial);

package/dist/tests/integration/cli.test.js

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 describe('CLI Integration', () => {
     describe('--help', () => {
         it('should display help information', () => {
-            const result = execSync('npm run build && node ./dist/src/cli.js --help', {
+            const result = execSync('yarn build && node ./dist/src/cli.js --help', {
                 encoding: 'utf-8',
                 cwd: resolve(__dirname, '../..'),
             });
@@ -15,7 +15,7 @@ describe('CLI Integration', () => {
     });
     describe('--version', () => {
         it('should display version information', () => {
-            const result = execSync('npm run build && node ./dist/src/cli.js --version', {
+            const result = execSync('yarn build && node ./dist/src/cli.js --version', {
                 encoding: 'utf-8',
                 cwd: resolve(__dirname, '../..'),
             });

package/examples/petstore/type.ts

@@ -1,6 +1,6 @@
 // THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-// Built with zod-codegen@1.0.1
-// Latest edit: Thu, 13 Nov 2025 13:36:35 GMT
+// Built with zod-codegen@1.1.2
+// Latest edit: Wed, 19 Nov 2025 16:26:25 GMT
 // Source file: ./samples/swagger-petstore.yaml
 /* eslint-disable */
 // @ts-nocheck
@@ -144,73 +144,209 @@ export class SwaggerPetstoreOpenAPI30 {
     if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
     return await response.json();
   }
-  async addPet(body: Pet): Promise<Pet> {
+  /**
+   * Add a new pet to the store
+   * @param body Create a new pet in the store
+   * @returns {z.infer<typeof Pet>}
+   */
+  async addPet(body: Pet): Promise<z.infer<typeof Pet>> {
     return Pet.parse(
       await this.#makeRequest('POST', '/pet', {data: body, contentType: 'application/x-www-form-urlencoded'}),
     );
   }
-  async updatePet(body: Pet): Promise<Pet> {
+  /**
+   * Update an existing pet
+   *
+   * Update an existing pet by Id
+   * @param body Update an existent pet in the store
+   * @returns {z.infer<typeof Pet>}
+   */
+  async updatePet(body: Pet): Promise<z.infer<typeof Pet>> {
     return Pet.parse(
       await this.#makeRequest('PUT', '/pet', {data: body, contentType: 'application/x-www-form-urlencoded'}),
     );
   }
-  async findPetsByStatus(status?: string): Promise<Pet[]> {
+  /**
+   * Finds Pets by status
+   *
+   * Multiple status values can be provided with comma separated strings
+   *
+   * @param status Status values that need to be considered for filter
+   * @returns {z.infer<typeof Pet>[]}
+   */
+  async findPetsByStatus(status?: string): Promise<z.infer<typeof Pet>[]> {
     return await this.#makeRequest('GET', '/pet/findByStatus', {params: {status: status}});
   }
-  async findPetsByTags(tags?: string[]): Promise<Pet[]> {
+  /**
+   * Finds Pets by tags
+   *
+   * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
+   *
+   * @param tags Tags to filter by
+   * @returns {z.infer<typeof Pet>[]}
+   */
+  async findPetsByTags(tags?: string[]): Promise<z.infer<typeof Pet>[]> {
     return await this.#makeRequest('GET', '/pet/findByTags', {params: {tags: tags}});
   }
-  async getPetById(petId: number): Promise<Pet> {
+  /**
+   * Find pet by ID
+   *
+   * Returns a single pet
+   *
+   * @param petId ID of pet to return
+   * @returns {z.infer<typeof Pet>}
+   */
+  async getPetById(petId: number): Promise<z.infer<typeof Pet>> {
     return Pet.parse(await this.#makeRequest('GET', `/pet/${petId}`, {}));
   }
+  /**
+   * Updates a pet in the store with form data
+   *
+   * @param petId ID of pet that needs to be updated
+   * @param name Name of pet that needs to be updated
+   * @param status Status of pet that needs to be updated
+   * @returns {void}
+   */
   async updatePetWithForm(petId: number, name?: string, status?: string): Promise<void> {
     return await this.#makeRequest('POST', `/pet/${petId}`, {params: {name: name, status: status}});
   }
+  /**
+   * Deletes a pet
+   *
+   * delete a pet
+   *
+   * @param api_key
+   * @param petId Pet id to delete
+   * @returns {void}
+   */
   async deletePet(petId: number): Promise<void> {
     return await this.#makeRequest('DELETE', `/pet/${petId}`, {});
   }
-  async uploadFile(petId: number, additionalMetadata?: string): Promise<ApiResponse> {
+  /**
+   * uploads an image
+   *
+   * @param petId ID of pet to update
+   * @param additionalMetadata Additional Metadata
+   * @param body
+   * @returns {z.infer<typeof ApiResponse>}
+   */
+  async uploadFile(petId: number, additionalMetadata?: string): Promise<z.infer<typeof ApiResponse>> {
     return ApiResponse.parse(
       await this.#makeRequest('POST', `/pet/${petId}/uploadImage`, {params: {additionalMetadata: additionalMetadata}}),
     );
   }
+  /**
+   * Returns pet inventories by status
+   *
+   * Returns a map of status codes to quantities
+   * @returns {Record<string, unknown>}
+   */
   async getInventory(): Promise<Record<string, unknown>> {
     return await this.#makeRequest('GET', '/store/inventory', {});
   }
-  async placeOrder(body?: Order): Promise<Order> {
+  /**
+   * Place an order for a pet
+   *
+   * Place a new order in the store
+   * @param body
+   * @returns {z.infer<typeof Order>}
+   */
+  async placeOrder(body?: Order): Promise<z.infer<typeof Order>> {
     return Order.parse(
       await this.#makeRequest('POST', '/store/order', {data: body, contentType: 'application/x-www-form-urlencoded'}),
     );
   }
-  async getOrderById(orderId: number): Promise<Order> {
+  /**
+   * Find purchase order by ID
+   *
+   * For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
+   *
+   * @param orderId ID of order that needs to be fetched
+   * @returns {z.infer<typeof Order>}
+   */
+  async getOrderById(orderId: number): Promise<z.infer<typeof Order>> {
     return Order.parse(await this.#makeRequest('GET', `/store/order/${orderId}`, {}));
   }
+  /**
+   * Delete purchase order by ID
+   *
+   * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+   *
+   * @param orderId ID of the order that needs to be deleted
+   * @returns {void}
+   */
   async deleteOrder(orderId: number): Promise<void> {
     return await this.#makeRequest('DELETE', `/store/order/${orderId}`, {});
   }
-  async createUser(body?: User): Promise<User> {
+  /**
+   * Create user
+   *
+   * This can only be done by the logged in user.
+   * @param body Created user object
+   * @returns {z.infer<typeof User>}
+   */
+  async createUser(body?: User): Promise<z.infer<typeof User>> {
     return User.parse(
       await this.#makeRequest('POST', '/user', {data: body, contentType: 'application/x-www-form-urlencoded'}),
     );
   }
-  async createUsersWithListInput(body?: User[]): Promise<User> {
+  /**
+   * Creates list of users with given input array
+   * @param body
+   * @returns {z.infer<typeof User>}
+   */
+  async createUsersWithListInput(body?: User[]): Promise<z.infer<typeof User>> {
     return User.parse(await this.#makeRequest('POST', '/user/createWithList', {data: body}));
   }
+  /**
+   * Logs user into the system
+   *
+   * @param username The user name for login
+   * @param password The password for login in clear text
+   * @returns {string}
+   */
   async loginUser(username?: string, password?: string): Promise<string> {
     return await this.#makeRequest('GET', '/user/login', {params: {username: username, password: password}});
   }
+  /**
+   * Logs out current logged in user session
+   * @returns {void}
+   */
   async logoutUser(): Promise<void> {
     return await this.#makeRequest('GET', '/user/logout', {});
   }
-  async getUserByName(username: string): Promise<User> {
+  /**
+   * Get user by user name
+   *
+   * @param username The name that needs to be fetched. Use user1 for testing.
+   * @returns {z.infer<typeof User>}
+   */
+  async getUserByName(username: string): Promise<z.infer<typeof User>> {
     return User.parse(await this.#makeRequest('GET', `/user/${username}`, {}));
   }
+  /**
+   * Update user
+   *
+   * This can only be done by the logged in user.
+   *
+   * @param username name that need to be deleted
+   * @param body Update an existent user in the store
+   * @returns {void}
+   */
   async updateUser(username: string, body?: User): Promise<void> {
     return await this.#makeRequest('PUT', `/user/${username}`, {
       data: body,
       contentType: 'application/x-www-form-urlencoded',
     });
   }
+  /**
+   * Delete user
+   *
+   * This can only be done by the logged in user.
+   *
+   * @param username The name that needs to be deleted
+   * @returns {void}
+   */
   async deleteUser(username: string): Promise<void> {
     return await this.#makeRequest('DELETE', `/user/${username}`, {});
   }

package/package.json

@@ -8,13 +8,13 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "debug": "^4.3.7",
+    "debug": "^4.4.3",
     "js-yaml": "^4.1.1",
     "jsonpath": "^1.1.1",
     "loud-rejection": "^2.2.0",
     "openapi-types": "^12.1.3",
     "openapi-typescript": "^7.10.1",
-    "path-to-regexp": "^8.2.0",
+    "path-to-regexp": "^8.3.0",
     "prettier": "^3.6.2",
     "typescript": "^5.9.3",
     "url-pattern": "^1.0.3",
@@ -44,8 +44,8 @@
     "@types/js-yaml": "^4.0.9",
     "@types/jsonpath": "^0.2.4",
     "@types/node": "^24.10.1",
-    "@types/yargs": "^17.0.34",
-    "@vitest/coverage-v8": "^4.0.8",
+    "@types/yargs": "^17.0.35",
+    "@vitest/coverage-v8": "^4.0.9",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "husky": "^9.1.7",
@@ -54,7 +54,8 @@
     "ts-node": "^10.9.2",
     "typescript-eslint": "^8.46.4",
     "undici": "^7.16.0",
-    "vitest": "^4.0.8"
+    "vitest": "^4.0.8",
+    "yarn-audit-fix": "^10.1.1"
   },
   "optionalDependencies": {
     "undici": "^7.16.0"
@@ -77,11 +78,20 @@
   "engines": {
     "node": ">=24.11.1"
   },
+  "overrides": {
+    "npm": {
+      "glob": "^11.1.0",
+      "tar": "^7.5.2"
+    },
+    "glob": "^11.1.0",
+    "tar": "^7.5.2"
+  },
   "scripts": {
+    "audit:fix": "yarn-audit-fix",
     "build": "rm -rf dist && tsc --project tsconfig.json && cp -r src/assets dist/src/ && chmod +x ./dist/src/cli.js",
     "build:native": "rm -rf dist && npx tsgo --project tsconfig.json && cp -r src/assets dist/src/ && chmod +x ./dist/src/cli.js",
     "build:watch": "tsc --project tsconfig.json --watch",
-    "dev": "npm run build && node ./dist/src/cli.js --input ./samples/swagger-petstore.yaml --output ./examples/petstore && npm run format && npm run lint",
+    "dev": "yarn build && node ./dist/src/cli.js --input ./samples/swagger-petstore.yaml --output ./examples/petstore && yarn format && yarn lint",
     "lint": "eslint src --fix",
     "lint:check": "eslint src",
     "format": "prettier src --write --log-level error",
@@ -93,12 +103,12 @@
     "test:ui": "vitest --ui",
     "manifest:update": "ts-node scripts/update-manifest.ts",
     "prepare": "husky",
-    "prepublishOnly": "npm run build && npm run test && npm run lint:check && npm run type-check",
+    "prepublishOnly": "yarn build && yarn test && yarn lint:check && yarn type-check",
     "clean": "rm -rf dist coverage node_modules/.cache",
-    "validate": "npm run type-check && npm run lint:check && npm run format:check && npm run test",
+    "validate": "yarn type-check && yarn lint:check && yarn format:check && yarn test",
     "validate:examples": "tsc -p ./tsconfig.examples.json --noEmit",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run"
   },
-  "version": "1.1.2"
+  "version": "1.2.1"
 }

package/src/services/code-generator.service.ts

@@ -962,7 +962,7 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
       statements.push(ts.factory.createReturnStatement(ts.factory.createAwaitExpression(makeRequestCall)));
     }
 
-    return ts.factory.createMethodDeclaration(
+    const methodDeclaration = ts.factory.createMethodDeclaration(
       [ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)],
       undefined,
       ts.factory.createIdentifier(String(schema.operationId)),
@@ -972,6 +972,22 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
       responseType,
       ts.factory.createBlock(statements, true),
     );
+
+    // Add JSDoc comment if summary or description exists
+    const jsdocComment = this.buildJSDocComment(schema.summary, schema.description, schema, responseType);
+
+    if (jsdocComment) {
+      // addSyntheticLeadingComment expects the comment content without delimiters
+      // and will wrap it in /** */ for JSDoc-style comments
+      ts.addSyntheticLeadingComment(
+        methodDeclaration,
+        ts.SyntaxKind.MultiLineCommentTrivia,
+        `*\n${jsdocComment}\n `,
+        true,
+      );
+    }
+
+    return methodDeclaration;
   }
 
   private buildPathExpression(path: string, pathParams: {name: string; type: string}[]): ts.Expression {
@@ -1248,10 +1264,48 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
 
     const responseSchema = response.content['application/json'].schema;
     const typeName = this.getSchemaTypeName(responseSchema, schemas);
+    const inferredType = this.wrapTypeWithZInfer(typeName, schemas);
 
-    return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier('Promise'), [
-      ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined),
-    ]);
+    return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier('Promise'), [inferredType]);
+  }
+
+  private wrapTypeWithZInfer(typeName: string, schemas: Record<string, ts.VariableStatement>): ts.TypeNode {
+    // Primitive types and Record types don't need z.infer
+    const primitiveTypes = ['string', 'number', 'boolean', 'unknown'];
+    if (primitiveTypes.includes(typeName) || typeName.startsWith('Record<')) {
+      return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
+    }
+
+    // Handle array types like "Pet[]"
+    if (typeName.endsWith('[]')) {
+      const itemTypeName = typeName.slice(0, -2);
+      const sanitizedItemTypeName = this.typeBuilder.sanitizeIdentifier(itemTypeName);
+
+      // Check if the item type is a custom schema
+      if (schemas[sanitizedItemTypeName]) {
+        // Return z.infer<typeof ItemType>[]
+        const zInferType = ts.factory.createTypeReferenceNode(
+          ts.factory.createQualifiedName(ts.factory.createIdentifier('z'), ts.factory.createIdentifier('infer')),
+          [ts.factory.createTypeQueryNode(ts.factory.createIdentifier(sanitizedItemTypeName), undefined)],
+        );
+        return ts.factory.createArrayTypeNode(zInferType);
+      }
+      // If it's a primitive array, return as-is
+      return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
+    }
+
+    // Handle custom schema types
+    const sanitizedTypeName = this.typeBuilder.sanitizeIdentifier(typeName);
+    if (schemas[sanitizedTypeName]) {
+      // Return z.infer<typeof TypeName>
+      return ts.factory.createTypeReferenceNode(
+        ts.factory.createQualifiedName(ts.factory.createIdentifier('z'), ts.factory.createIdentifier('infer')),
+        [ts.factory.createTypeQueryNode(ts.factory.createIdentifier(sanitizedTypeName), undefined)],
+      );
+    }
+
+    // Fallback: return as-is if we can't determine
+    return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(typeName), undefined);
   }
 
   private buildServerConfiguration(openapi: OpenApiSpecType): ts.Statement[] {
@@ -1670,6 +1724,96 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
     return ts.factory.createExpressionStatement(commentNode);
   }
 
+  /**
+   * Builds a JSDoc comment string from operation metadata
+   */
+  private buildJSDocComment(
+    summary: string | undefined,
+    description: string | undefined,
+    schema: MethodSchemaType,
+    responseType: ts.TypeNode | undefined,
+  ): string {
+    const lines: string[] = [];
+
+    // Add summary or description as the main comment
+    if (summary) {
+      lines.push(` * ${summary}`);
+    } else if (description) {
+      // Use first line of description as summary if no summary exists
+      const firstLine = description.split('\n')[0]?.trim();
+      if (firstLine) {
+        lines.push(` * ${firstLine}`);
+      }
+    }
+
+    // Add full description if it exists and is different from summary
+    if (description && description !== summary) {
+      const descLines = description.split('\n');
+      if (descLines.length > 1 || descLines[0] !== summary) {
+        if (lines.length > 0) {
+          lines.push(' *');
+        }
+        descLines.forEach((line) => {
+          lines.push(` * ${line.trim() || ''}`);
+        });
+      }
+    }
+
+    // Add @param tags for each parameter
+    if (schema.parameters && schema.parameters.length > 0) {
+      if (lines.length > 0) {
+        lines.push(' *');
+      }
+      for (const param of schema.parameters) {
+        const paramName = this.typeBuilder.sanitizeIdentifier(param.name);
+        const paramDesc = param.description ? ` ${param.description}` : '';
+        lines.push(` * @param ${paramName}${paramDesc}`);
+      }
+    }
+
+    // Add @param tag for request body if present
+    if (schema.requestBody) {
+      const bodyDesc = schema.requestBody.description ? ` ${schema.requestBody.description}` : '';
+      lines.push(` * @param body${bodyDesc}`);
+    }
+
+    // Add @returns tag if we have a response type
+    if (responseType) {
+      // Extract the inner type from Promise<T> for JSDoc
+      let returnTypeText: string;
+      if (
+        ts.isTypeReferenceNode(responseType) &&
+        ts.isIdentifier(responseType.typeName) &&
+        responseType.typeName.text === 'Promise' &&
+        responseType.typeArguments &&
+        responseType.typeArguments.length > 0 &&
+        responseType.typeArguments[0]
+      ) {
+        // Extract the inner type from Promise<T>
+        const innerType = responseType.typeArguments[0];
+        returnTypeText = this.printer.printNode(
+          ts.EmitHint.Unspecified,
+          innerType,
+          ts.createSourceFile('', '', ts.ScriptTarget.Latest),
+        );
+      } else {
+        returnTypeText = this.printer.printNode(
+          ts.EmitHint.Unspecified,
+          responseType,
+          ts.createSourceFile('', '', ts.ScriptTarget.Latest),
+        );
+      }
+      lines.push(` * @returns {${returnTypeText}}`);
+    }
+
+    // Build the complete JSDoc comment (without delimiters, as addSyntheticLeadingComment adds them)
+    if (lines.length === 0) {
+      return '';
+    }
+
+    return lines.join('\n');
+  }
+
   private buildZodAST(input: (string | z.infer<typeof this.ZodAST>)[]): ts.CallExpression {
     const [initial, ...rest] = input;
 

package/tests/integration/cli.test.ts

@@ -5,7 +5,7 @@ import {resolve} from 'node:path';
 describe('CLI Integration', () => {
   describe('--help', () => {
     it('should display help information', () => {
-      const result = execSync('npm run build && node ./dist/src/cli.js --help', {
+      const result = execSync('yarn build && node ./dist/src/cli.js --help', {
         encoding: 'utf-8',
         cwd: resolve(__dirname, '../..'),
       });
@@ -18,7 +18,7 @@ describe('CLI Integration', () => {
 
   describe('--version', () => {
     it('should display version information', () => {
-      const result = execSync('npm run build && node ./dist/src/cli.js --version', {
+      const result = execSync('yarn build && node ./dist/src/cli.js --version', {
         encoding: 'utf-8',
         cwd: resolve(__dirname, '../..'),
       });