@eqxjs/swagger-codegen 1.0.0-beta.0

package/OPENAPI-COMPARISON.md

@@ -0,0 +1,355 @@
+# OpenAPI 3.0 vs Swagger 2.0 Examples
+
+This document compares the key differences between Swagger 2.0 and OpenAPI 3.0 specifications as demonstrated in the example files.
+
+## Quick Reference
+
+| Feature | Swagger 2.0 | OpenAPI 3.0 |
+|---------|-------------|-------------|
+| Version Field | `swagger: "2.0"` | `openapi: "3.0.0"` |
+| Schema Location | `definitions` | `components.schemas` |
+| Request Body | `parameters` with `in: body` | `requestBody` object |
+| Response Content | Direct `schema` | `content` > media type > `schema` |
+| Servers | `host`, `basePath`, `schemes` | `servers` array |
+| Example Files | `example-swagger.json/yaml` | `openapi3-example.json/yaml` |
+
+## Detailed Differences
+
+### 1. API Metadata
+
+**Swagger 2.0:**
+```yaml
+swagger: '2.0'
+host: api.example.com
+basePath: /api/v1
+schemes:
+  - https
+```
+
+**OpenAPI 3.0:**
+```yaml
+openapi: 3.0.0
+servers:
+  - url: https://api.example.com/v2
+    description: Production server
+  - url: https://staging.example.com/v2
+    description: Staging server
+```
+
+### 2. Schema Definitions
+
+**Swagger 2.0:**
+```yaml
+definitions:
+  User:
+    type: object
+    properties:
+      id:
+        type: string
+    required:
+      - id
+```
+
+**OpenAPI 3.0:**
+```yaml
+components:
+  schemas:
+    Product:
+      type: object
+      properties:
+        id:
+          type: string
+      required:
+        - id
+```
+
+### 3. Request Body
+
+**Swagger 2.0:**
+```yaml
+post:
+  parameters:
+    - in: body
+      name: body
+      required: true
+      schema:
+        $ref: '#/definitions/CreateUserDto'
+```
+
+**OpenAPI 3.0:**
+```yaml
+post:
+  requestBody:
+    required: true
+    description: Product information
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/CreateProductDto'
+```
+
+### 4. Response Definition
+
+**Swagger 2.0:**
+```yaml
+responses:
+  '200':
+    description: Successful response
+    schema:
+      type: array
+      items:
+        $ref: '#/definitions/User'
+```
+
+**OpenAPI 3.0:**
+```yaml
+responses:
+  '200':
+    description: Successful response
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: '#/components/schemas/Product'
+```
+
+### 5. Query Parameters
+
+**Swagger 2.0:**
+```yaml
+parameters:
+  - name: page
+    in: query
+    type: integer
+    required: false
+```
+
+**OpenAPI 3.0:**
+```yaml
+parameters:
+  - name: page
+    in: query
+    required: false
+    schema:
+      type: integer
+      default: 1
+      minimum: 1
+```
+
+### 6. Path Parameters
+
+**Swagger 2.0:**
+```yaml
+parameters:
+  - name: id
+    in: path
+    required: true
+    type: string
+    description: User ID
+```
+
+**OpenAPI 3.0:**
+```yaml
+parameters:
+  - name: id
+    in: path
+    required: true
+    description: Product ID
+    schema:
+      type: string
+      format: uuid
+```
+
+## Code Generation Output
+
+Both specifications generate the same NestJS structure:
+
+```
+generated/
+├── dtos/           # DTOs with @ApiProperty decorators
+├── products/       # Product feature module
+│   ├── products.service.ts
+│   ├── products.controller.ts
+│   └── products.module.ts
+├── categories/     # Category feature module
+│   ├── categories.service.ts
+│   ├── categories.controller.ts
+│   └── categories.module.ts
+├── app.module.ts   # Root module
+└── index.ts        # Barrel exports
+```
+
+**Note:** Service, controller, and module for each resource are grouped together by tag name.
+
+### Example DTO Output
+
+Both generate similar TypeScript classes:
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class Product {
+  @ApiProperty({ description: 'Unique product identifier', type: String })
+  id: string;
+
+  @ApiProperty({ description: 'Product name', type: String })
+  name: string;
+
+  @ApiProperty({ description: 'Product price in USD', type: Number })
+  price: number;
+
+  @ApiProperty({ description: 'Product tags', isArray: true })
+  tags?: string[];
+
+  @ApiProperty({ 
+    description: 'Product status', 
+    enum: ['active', 'inactive', 'discontinued'] 
+  })
+  status?: string;
+}
+```
+
+### Example Controller Output
+
+Both generate controllers with proper decorators:
+
+```typescript
+@ApiTags('products')
+@Controller('products')
+export class ProductsController {
+  constructor(private readonly productsService: ProductsService) {}
+
+  @ApiOperation({ summary: 'List all products' })
+  @Get('')
+  async listProducts(
+    @Query('page') page: string,
+    @Query('limit') limit: string
+  ): Promise<any> {
+    return this.productsService.listProducts(page, limit);
+  }
+
+  @ApiOperation({ summary: 'Create a new product' })
+  @Post('')
+  async createProduct(@Body() body: CreateProductDto): Promise<any> {
+    return this.productsService.createProduct(body);
+  }
+}
+```
+
+## Testing the Examples
+
+### Swagger 2.0
+```bash
+# JSON
+npm run dev -- generate -i ./example-swagger.json -o ./generated
+
+# YAML
+npm run dev -- generate -i ./example-swagger.yaml -o ./generated
+```
+
+**Generated:**
+- 5 DTOs (User, CreateUserDto, UpdateUserDto, Post, CreatePostDto)
+- 2 Services (UsersService, PostsService)
+- 2 Controllers (UsersController, PostsController)
+- 2 Modules (UsersModule, PostsModule)
+
+### OpenAPI 3.0
+```bash
+# JSON
+npm run dev -- generate -i ./openapi3-example.json -o ./generated
+
+# YAML
+npm run dev -- generate -i ./openapi3-example.yaml -o ./generated
+```
+
+**Generated:**
+- 6 DTOs (Product, CreateProductDto, UpdateProductDto, Category, CreateCategoryDto, Error)
+- 2 Services (ProductsService, CategoriesService)
+- 2 Controllers (ProductsController, CategoriesController)
+- 2 Modules (ProductsModule, CategoriesModule)
+
+## Advanced Features in OpenAPI 3.0
+
+The OpenAPI 3.0 examples demonstrate additional features:
+
+### 1. Multiple Servers
+Define multiple deployment environments:
+```yaml
+servers:
+  - url: https://api.example.com/v2
+    description: Production server
+  - url: https://staging.example.com/v2
+    description: Staging server
+```
+
+### 2. Enhanced Parameter Validation
+```yaml
+schema:
+  type: integer
+  minimum: 1
+  maximum: 100
+  default: 10
+```
+
+### 3. Content Negotiation
+```yaml
+content:
+  application/json:
+    schema: {...}
+  application/xml:
+    schema: {...}
+```
+
+### 4. Reusable Error Schemas
+```yaml
+components:
+  schemas:
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+```
+
+## Migration from Swagger 2.0 to OpenAPI 3.0
+
+This tool supports both versions seamlessly, but if you're migrating:
+
+### Key Changes to Make:
+
+1. **Update version field:**
+   - Change `swagger: "2.0"` to `openapi: "3.0.0"`
+
+2. **Move schemas:**
+   - Move `definitions` to `components.schemas`
+
+3. **Update request bodies:**
+   - Replace body parameters with `requestBody` object
+
+4. **Update responses:**
+   - Wrap response schemas in `content` object with media types
+
+5. **Update servers:**
+   - Replace `host`, `basePath`, `schemes` with `servers` array
+
+6. **Update parameter schemas:**
+   - Wrap parameter types in `schema` object
+
+## Recommendation
+
+- **Use Swagger 2.0** if you're maintaining legacy APIs or need broader tool support
+- **Use OpenAPI 3.0** for new projects to take advantage of:
+  - Better content negotiation
+  - Clearer request/response definitions
+  - Multiple server support
+  - Enhanced validation options
+  - Callback definitions
+  - Link definitions
+
+Both versions generate **identical NestJS code** with this tool! 🎉

package/QUICKSTART.md

@@ -0,0 +1,118 @@
+# Quick Start Guide
+
+## Available Example Files
+
+### 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
+
+### 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
+
+## Quick Commands
+
+```bash
+# Install & Build
+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
+
+# Clean Generated Files
+npm run clean
+```
+
+## Generate Code
+
+Choose any example file:
+
+```bash
+# Swagger 2.0 - JSON
+npm run dev -- 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
+
+# OpenAPI 3.0 - JSON
+npm run dev -- 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
+```
+
+## Generated Structure
+
+```
+output/
+├── 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
+```
+
+**Structure:** Each resource (tag) has its service, controller, and module grouped together in the same folder.
+
+## Example Output
+
+### DTO
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class Product {
+  @ApiProperty({ description: 'Product ID', type: String })
+  id: string;
+
+  @ApiProperty({ description: 'Product name', type: String })
+  name: string;
+}
+```
+
+### Controller
+```typescript
+@ApiTags('products')
+@Controller('products')
+export class ProductsController {
+  @ApiOperation({ summary: 'List products' })
+  @Get('')
+  async listProducts(): Promise<Product[]> {
+    return this.productsService.listProducts();
+  }
+}
+```
+
+## Documentation
+
+- **[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
+
+✅ 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  
+
+## Need Help?
+
+See the full documentation in [README.md](README.md) for detailed usage instructions and examples.