@eqxjs/swagger-codegen 1.0.0-beta.1 → 1.0.0-beta.2

package/QUICKSTART.md

@@ -1,118 +1,452 @@
 # Quick Start Guide
 
-## Available Example Files
+Get started with `@eqxjs/swagger-codegen` in minutes!
 
-### Swagger 2.0 Examples
-- **`example-swagger.json`** (8.1KB) - Users & Posts API
-- **`example-swagger.yaml`** (5.8KB) - Users & Posts API
-  - 5 DTOs, 2 Services, 2 Controllers, 2 Modules
+## 📦 Installation
 
-### OpenAPI 3.0 Examples
-- **`openapi3-example.json`** (14KB) - Products & Categories API
-- **`openapi3-example.yaml`** (10KB) - Products & Categories API  
-  - 6 DTOs, 2 Services, 2 Controllers, 2 Modules
+### Option 1: Global Installation
+```bash
+npm install -g @eqxjs/swagger-codegen
+```
 
-## Quick Commands
+### Option 2: Use with npx (No Installation)
+```bash
+npx @eqxjs/swagger-codegen generate -i ./swagger.json -o ./generated
+```
 
+### Option 3: Development from Source
 ```bash
-# Install & Build
+git clone <repository-url>
+cd swagger-nestjs-codegen
 npm install
 npm run build
+```
 
-# Test a Single Format
-npm run dev -- generate -i ./example-swagger.json -o ./generated
+---
 
-# Test All Formats
-npm run test:all
+## 🚀 Basic Usage
 
-# Clean Generated Files
-npm run clean
+### Generate Server Code (Default)
+```bash
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated
+```
+
+### Generate with Test Files
+```bash
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated --with-test
+```
+
+### Generate Client Code
+```bash
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated --mode client
+```
+
+### Generate Both Server & Client
+```bash
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated --mode both
 ```
 
-## Generate Code
+---
+
+## 📋 Available Example Files
+
+This repository includes example Swagger/OpenAPI files for testing:
 
-Choose any example file:
+| File | Format | Spec | Description |
+|------|--------|------|-------------|
+| `example-swagger.json` | JSON | Swagger 2.0 | Users & Posts API (5 DTOs, 2 modules) |
+| `example-swagger.yaml` | YAML | Swagger 2.0 | Same API, 28% smaller file |
+| `openapi3-example.json` | JSON | OpenAPI 3.0 | Products & Categories API (6 DTOs, 2 modules) |
+| `openapi3-example.yaml` | YAML | OpenAPI 3.0 | Same API, 29% smaller file |
+
+### Try the Examples
 
 ```bash
-# Swagger 2.0 - JSON
-npm run dev -- generate -i ./example-swagger.json -o ./output
+# Swagger 2.0 - JSON format
+eqxjs-swagger-codegen generate -i ./example-swagger.json -o ./output
 
-# Swagger 2.0 - YAML (28% smaller than JSON)
-npm run dev -- generate -i ./example-swagger.yaml -o ./output
+# Swagger 2.0 - YAML format
+eqxjs-swagger-codegen generate -i ./example-swagger.yaml -o ./output
 
-# OpenAPI 3.0 - JSON
-npm run dev -- generate -i ./openapi3-example.json -o ./output
+# OpenAPI 3.0 - JSON format
+eqxjs-swagger-codegen generate -i ./openapi3-example.json -o ./output
 
-# OpenAPI 3.0 - YAML (29% smaller than JSON)
-npm run dev -- generate -i ./openapi3-example.yaml -o ./output
+# OpenAPI 3.0 - YAML format
+eqxjs-swagger-codegen generate -i ./openapi3-example.yaml -o ./output
 ```
 
-## Generated Structure
+### Development Mode Commands
+
+If you're developing the tool itself:
+
+```bash
+# Install dependencies
+npm install
+
+# Test with an example
+npm run dev -- generate -i ./example-swagger.json -o ./generated
+
+# Test all formats at once
+npm run test:all
 
+# Clean generated files
+npm run clean
 ```
-output/
+
+---
+
+---
+
+## 📁 Generated Structure
+
+### Without Tests (Default)
+```
+generated/
+├── dtos/
+│   ├── user.dto.ts              # Data Transfer Objects with validation
+│   ├── post.dto.ts
+│   └── product.dto.ts
+├── users/
+│   ├── users.service.ts         # Injectable service with business logic
+│   ├── users.controller.ts      # REST API endpoints
+│   └── users.module.ts          # Feature module
+├── posts/
+│   ├── posts.service.ts
+│   ├── posts.controller.ts
+│   └── posts.module.ts
+├── app.module.ts                # Root application module (auto-updated)
+└── index.ts                     # Barrel exports
+```
+
+### With Tests (`--with-test` flag)
+```
+generated/
 ├── dtos/
-│   ├── *.dto.ts              # DTOs with @ApiProperty
-├── products/
-│   ├── products.service.ts   # Injectable service
-│   ├── products.controller.ts # Controller with routes
-│   └── products.module.ts    # Feature module
-├── categories/
-│   ├── categories.service.ts
-│   ├── categories.controller.ts
-│   └── categories.module.ts
-├── app.module.ts             # Root module
-└── index.ts                  # Barrel exports
+│   ├── user.dto.ts
+│   └── post.dto.ts
+├── users/
+│   ├── users.service.ts
+│   ├── users.controller.ts
+│   └── users.module.ts
+├── tests/                        # Separate test directory
+│   ├── dtos/
+│   │   ├── user.dto.spec.ts     # DTO validation tests
+│   │   └── post.dto.spec.ts
+│   └── users/
+│       ├── users.service.spec.ts    # Service unit tests
+│       └── users.controller.spec.ts # Controller tests with mocks
+├── app.module.ts
+└── index.ts
 ```
 
-**Structure:** Each resource (tag) has its service, controller, and module grouped together in the same folder.
+**Key Points:**
+- Each resource (Swagger tag) gets its own folder with service, controller, and module
+- All DTOs are grouped in the `dtos/` folder
+- Tests mirror the source structure in a separate `tests/` directory
+- `app.module.ts` is automatically updated with all generated modules
+
+---
 
-## Example Output
+## 📝 Example Output
 
-### DTO
+### DTO with Validation
 ```typescript
 import { ApiProperty } from '@nestjs/swagger';
 
-export class Product {
-  @ApiProperty({ description: 'Product ID', type: String })
-  id: string;
+export class CreateUserDto {
+  @ApiProperty({ description: 'User email address', type: String })
+  email: string;
 
-  @ApiProperty({ description: 'Product name', type: String })
+  @ApiProperty({ description: 'User full name', type: String })
   name: string;
+
+  @ApiProperty({ description: 'User age', type: Number, required: false })
+  age?: number;
+}
+```
+
+### Service
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CreateUserDto } from '../dtos/create-user.dto';
+import { User } from '../dtos/user.dto';
+
+@Injectable()
+export class UsersService {
+  async createUser(createUserDto: CreateUserDto): Promise<User> {
+    // Implementation here
+    throw new Error('Not implemented');
+  }
+
+  async getUser(id: string): Promise<User> {
+    // Implementation here
+    throw new Error('Not implemented');
+  }
 }
 ```
 
 ### Controller
 ```typescript
-@ApiTags('products')
-@Controller('products')
-export class ProductsController {
-  @ApiOperation({ summary: 'List products' })
-  @Get('')
-  async listProducts(): Promise<Product[]> {
-    return this.productsService.listProducts();
+import { Controller, Get, Post, Body, Param } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from '../dtos/create-user.dto';
+import { User } from '../dtos/user.dto';
+
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({ status: 201, description: 'User created', type: User })
+  @Post()
+  async createUser(@Body() createUserDto: CreateUserDto): Promise<User> {
+    return this.usersService.createUser(createUserDto);
+  }
+
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiResponse({ status: 200, description: 'User found', type: User })
+  @Get(':id')
+  async getUser(@Param('id') id: string): Promise<User> {
+    return this.usersService.getUser(id);
   }
 }
 ```
 
-## Documentation
+### Generated Test (with `--with-test`)
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersController } from '../../users/users.controller';
+import { UsersService } from '../../users/users.service';
+
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: UsersService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            createUser: jest.fn(),
+            getUser: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UsersController>(UsersController);
+    service = module.get<UsersService>(UsersService);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+});
+```
+
+---
+
+## ⚙️ Command Options
+
+```bash
+eqxjs-swagger-codegen generate [options]
+
+Options:
+  -i, --input <path>    Path to Swagger/OpenAPI file (JSON or YAML) [required]
+  -o, --output <path>   Output directory for generated files (default: "./generated")
+  -m, --mode <mode>     Generation mode: server, client, or both (default: "server")
+  --with-test          Generate test files (.spec.ts) for all generated code
+  --with-validate      Add class-validator decorators to DTOs
+  --only-dtos          Generate only DTOs (skip services, controllers, modules)
+  -h, --help           Display help for command
+```
+
+### Examples
+
+```bash
+# Basic server generation
+eqxjs-swagger-codegen generate -i ./api.json -o ./src/generated
+
+# Client SDK generation
+eqxjs-swagger-codegen generate -i ./api.json -o ./client --mode client
+
+# Both server and client
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --mode both
+
+# With comprehensive test suite
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --with-test
+
+# With validation decorators
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --with-validate
+
+# Only DTOs with validators (no services/controllers)
+eqxjs-swagger-codegen generate -i ./api.json -o ./dtos --only-dtos --with-validate
+
+# Complete setup: server + tests + validators
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --with-test --with-validate
+
+# Using npx (no installation)
+npx @eqxjs/swagger-codegen generate -i ./api.yaml -o ./generated --with-validate
+```
+
+---
+
+---
+
+## ✨ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔄 **Multiple Specs** | Supports Swagger 2.0 & OpenAPI 3.0 |
+| 📄 **Multiple Formats** | Accepts both JSON & YAML files |
+| 🎯 **Type Safety** | Generates fully typed TypeScript code |
+| 🏗️ **Complete Modules** | Creates services, controllers, and modules |
+| 📚 **Swagger Decorators** | Includes @ApiTags, @ApiOperation, @ApiResponse, etc. |
+| 🔗 **Schema References** | Handles $ref, allOf, oneOf, anyOf compositions |
+| 🧪 **Test Generation** | Creates comprehensive test suites with `--with-test` |
+| ✅ **Validation** | Adds class-validator decorators with `--with-validate` |
+| 📦 **Flexible Output** | Generate server, client, both, or DTOs only |
+| 🔌 **Three Modes** | Generate server, client, or both |
+| 🔧 **Auto Module Import** | Updates app.module.ts automatically |
+| 🚫 **No Self-Imports** | Prevents circular dependency issues in DTOs |
+
+---
+
+## 🎯 Generation Modes
+
+### Server Mode (Default)
+Generates NestJS backend code:
+- Controllers with REST endpoints
+- Injectable services
+- Feature modules
+- DTOs with Swagger decorators
+
+```bash
+eqxjs-swagger-codegen generate -i ./api.json -o ./server
+```
+
+### Client Mode
+Generates TypeScript client SDK:
+- Axios-based HTTP client
+- Typed request/response interfaces
+- All API methods ready to use
+
+```bash
+eqxjs-swagger-codegen generate -i ./api.json -o ./client --mode client
+```
+
+### Both Mode
+Generates both server and client code in the same output directory:
+
+```bash
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --mode both
+```
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [README.md](README.md) | Complete documentation and usage guide |
+| [FORMATS.md](FORMATS.md) | JSON vs YAML format comparison |
+| [OPENAPI-COMPARISON.md](OPENAPI-COMPARISON.md) | Swagger 2.0 vs OpenAPI 3.0 differences |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture and design decisions |
+| [SUMMARY.md](SUMMARY.md) | Project overview and summary |
+
+---
+
+## 🆘 Common Use Cases
+
+### Use Case 1: Generate Backend from Existing API Spec
+```bash
+# You have an API specification and want to generate NestJS backend
+eqxjs-swagger-codegen generate -i ./my-api.yaml -o ./src/generated
+```
+
+### Use Case 2: Generate Client SDK for Frontend
+```bash
+# Generate TypeScript client for your React/Angular/Vue app
+eqxjs-swagger-codegen generate -i ./api.json -o ./src/api-client --mode client
+```
+
+### Use Case 3: Full-Stack with Tests
+```bash
+# Generate both server and client with complete test coverage
+eqxjs-swagger-codegen generate -i ./api.json -o ./generated --mode both --with-test
+```
+
+### Use Case 4: Quick Prototyping with Validation
+```bash
+# Generate DTOs with built-in validation for rapid API development
+npx @eqxjs/swagger-codegen generate -i ./prototype-api.yaml -o ./src --with-validate
+```
+
+### Use Case 5: Shared Type Library
+```bash
+# Generate only DTOs for a shared package across microservices
+eqxjs-swagger-codegen generate -i ./api-contract.json -o ./packages/types --only-dtos
+```
+
+---
+
+## 💡 Tips
+
+- **Use YAML files** - They're 28-29% smaller than JSON and easier to read
+- **Enable test generation** - Add `--with-test` for instant test coverage
+- **Add validators** - Use `--with-validate` for automatic DTO validation with class-validator
+- **DTOs only mode** - Use `--only-dtos` when you only need type definitions
+- **Check app.module.ts** - It's automatically updated with all generated modules
+- **Review generated code** - Services have placeholder implementations to fill in
+- **Run type checking** - Use `tsc --noEmit` to verify generated code compiles
+- **Install dependencies** - Generated tests require `@nestjs/testing` and `jest`
+- **Install validators** - `--with-validate` requires `class-validator` and `class-transformer`
+
+---
+
+## 🚀 Next Steps
+
+1. **Install the package**
+   ```bash
+   npm install -g @eqxjs/swagger-codegen
+   ```
+
+2. **Generate code from your Swagger/OpenAPI file**
+   ```bash
+   eqxjs-swagger-codegen generate -i ./your-api.yaml -o ./generated --with-test
+   ```
+
+3. **Review the generated code**
+   - Check DTOs in `generated/dtos/`
+   - Review controllers and services
+   - See `generated/app.module.ts` for module imports
+
+4. **Implement business logic**
+   - Fill in service method implementations
+   - Add database integration
+   - Implement error handling
+
+5. **Run tests**
+   ```bash
+   npm test
+   ```
+
+6. **Read the full documentation**
+   - See [README.md](README.md) for advanced features
+   - Check [ARCHITECTURE.md](ARCHITECTURE.md) for design details
 
-- **[README.md](README.md)** - Main documentation
-- **[FORMATS.md](FORMATS.md)** - JSON vs YAML comparison
-- **[OPENAPI-COMPARISON.md](OPENAPI-COMPARISON.md)** - Swagger 2.0 vs OpenAPI 3.0
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System architecture
-- **[SUMMARY.md](SUMMARY.md)** - Project overview
+---
 
-## Key Features
+## 📞 Need Help?
 
-✅ Supports Swagger 2.0 & OpenAPI 3.0  
-✅ Accepts JSON & YAML formats  
-✅ Generates type-safe TypeScript code  
-✅ Creates complete NestJS modules  
-✅ Includes Swagger decorators  
-✅ Handles complex schemas & references  
-✅ Supports path, query, and body parameters  
+- **Documentation**: [README.md](README.md)
+- **Issues**: Check the repository issues page
+- **Examples**: See the included example files in this repository
 
-## Need Help?
+---
 
-See the full documentation in [README.md](README.md) for detailed usage instructions and examples.
+**Happy Coding! 🎉**

package/README.md

@@ -31,7 +31,17 @@ A TypeScript CLI tool to generate NestJS modules, controllers, services, and DTO
 
 ## Installation
 
+### From NPM
+
+```bash
+npm install -g @eqxjs/swagger-codegen
+```
+
+### From Source
+
 ```bash
+git clone <repository-url>
+cd swagger-nestjs-codegen
 npm install
 npm run build
 ```
@@ -74,28 +84,138 @@ npm run dev -- generate -i ./openapi3-example.yaml -o ./generated
 ### Production Mode
 
 ```bash
-# Build the project first
-npm run build
+# Using the global CLI
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated
 
-# Run the CLI with JSON
-node dist/cli.js generate -i ./swagger.json -o ./generated
+# Using npx (no installation required)
+npx @eqxjs/swagger-codegen generate -i ./swagger.json -o ./generated
 
-# Run the CLI with YAML
-node dist/cli.js generate -i ./swagger.yaml -o ./generated
+# With YAML files
+eqxjs-swagger-codegen generate -i ./swagger.yaml -o ./generated
 
-# Or use the npm script
-npm start -- generate -i ./swagger.json -o ./generated
+# Local installation
+node dist/cli.js generate -i ./swagger.json -o ./generated
 ```
 
 ### Command Options
 
 ```bash
-swagger-nestjs-codegen generate [options]
+eqxjs-swagger-codegen generate [options]
 
 Options:
-  -i, --input <path>   Path to Swagger/OpenAPI file (JSON or YAML) [required]
-  -o, --output <path>  Output directory for generated files (default: "./generated")
-  -h, --help          Display help for command
+  -i, --input <path>    Path to Swagger/OpenAPI file (JSON or YAML) [required]
+  -o, --output <path>   Output directory for generated files (default: "./generated")
+  -m, --mode <mode>     Generation mode: server, client, or both (default: "server")
+  --with-test          Generate test files (.spec.ts) for all generated files
+  --with-validate      Add class-validator decorators to DTOs for validation
+  --only-dtos          Generate only DTOs (skip services, controllers, modules)
+  -h, --help           Display help for command
+```
+
+### Generating with Test Files
+
+Use the `--with-test` flag to automatically generate test files for all controllers, services, and DTOs:
+
+```bash
+# Generate with test files
+eqxjs-swagger-codegen generate -i ./example-swagger.json -o ./generated --with-test
+
+# Using npx
+npx @eqxjs/swagger-codegen generate -i ./swagger.json -o ./generated --with-test
+
+# Development mode
+npm run dev -- generate -i ./example-swagger.json -o ./generated --with-test
+```
+
+### Generating with Validation Decorators
+
+Use the `--with-validate` flag to add class-validator decorators to all DTO properties:
+
+```bash
+# Generate DTOs with validation decorators
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated --with-validate
+
+# Combine with test generation
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./generated --with-validate --with-test
+```
+
+**Generated validators include:**
+- `@IsString()`, `@IsNumber()`, `@IsInt()`, `@IsBoolean()`, `@IsDate()` for basic types
+- `@IsEmail()` for email format
+- `@IsUUID()` for UUID format
+- `@IsUrl()` for URL format
+- `@IsEnum()` for enum values
+- `@IsArray()` with `@IsString({ each: true })` for arrays
+- `@ValidateNested()` with `@Type()` for nested objects
+- `@Min()`, `@Max()` for number constraints
+- `@MinLength()`, `@MaxLength()` for string length
+- `@Matches()` for regex patterns
+
+**Example output:**
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsEmail, IsInt, Min } from 'class-validator';
+
+export class CreateUserDto {
+  @IsString()
+  @IsEmail()
+  @ApiProperty({ description: 'User email', type: String })
+  email!: string;
+
+  @IsInt()
+  @Min(18)
+  @ApiProperty({ description: 'User age', type: Number })
+  age!: number;
+}
+```
+
+### Generating Only DTOs
+
+Use the `--only-dtos` flag to generate only Data Transfer Objects without services, controllers, or modules:
+
+```bash
+# Generate only DTOs
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./dtos --only-dtos
+
+# DTOs with validators
+eqxjs-swagger-codegen generate -i ./swagger.json -o ./dtos --only-dtos --with-validate
+```
+
+This is useful when you:
+- Only need the data models for a separate project
+- Want to share DTOs between multiple services
+- Are building a monorepo and need consistent type definitions
+- Want to generate TypeScript interfaces from your API spec
+
+This will create test files alongside their corresponding source files:
+- **Controller specs**: Test files with mocked services and test cases for each endpoint
+- **Service specs**: Test files with basic setup and method existence checks
+- **DTO specs**: Test files with class-validator integration for validating DTOs
+
+**Example output:**
+```
+generated/
+├── dtos/
+│   ├── user.dto.ts
+│   └── post.dto.ts
+├── users/
+│   ├── users.service.ts
+│   ├── users.controller.ts
+│   └── users.module.ts
+├── posts/
+│   ├── posts.service.ts
+│   ├── posts.controller.ts
+│   └── posts.module.ts
+└── tests/                           # 🧪 Test files with same structure
+    ├── dtos/
+    │   ├── user.dto.spec.ts
+    │   └── post.dto.spec.ts
+    ├── users/
+    │   ├── users.controller.spec.ts
+    │   └── users.service.spec.ts
+    └── posts/
+        ├── posts.controller.spec.ts
+        └── posts.service.spec.ts
 ```
 
 ## Generated File Structure