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

package/ARCHITECTURE.md

@@ -2,183 +2,273 @@
 
 ## System Architecture
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                         CLI Entry Point                      │
-│                         (src/cli.ts)                         │
-│                    Commander.js Interface                    │
-└──────────────────────────┬──────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│                     Main Generator                           │
-│                   (src/generator.ts)                         │
-│              Orchestrates the generation flow                │
-└──────┬──────────────────┬──────────────────┬────────────────┘
-       │                  │                  │
-       ▼                  ▼                  ▼
-┌───────────────┐  ┌─────────────┐  ┌──────────────────┐
-│  Swagger      │  │   Utilities │  │   File Writer    │
-│   Parser      │  │             │  │                  │
-│ (parser.ts)   │  │ (utils.ts)  │  │(file-writer.ts)  │
-└───────┬───────┘  └──────┬──────┘  └────────┬─────────┘
-        │                 │                   │
-        │        ┌────────┴────────┐         │
-        │        │                 │         │
-        ▼        ▼                 ▼         ▼
-┌────────────────────────────────────────────────────────┐
-│              Code Generators (src/generators/)          │
-├────────────┬─────────────┬──────────────┬──────────────┤
-│    DTO     │  Service    │ Controller   │   Module     │
-│ Generator  │  Generator  │  Generator   │  Generator   │
-└────────────┴─────────────┴──────────────┴──────────────┘
-        │           │            │              │
-        └───────────┴────────────┴──────────────┘
-                           │
-                           ▼
-                  ┌────────────────┐
-                  │  Output Files  │
-                  │   (generated/) │
-                  └────────────────┘
+```mermaid
+graph TD
+    CLI["CLI Entry Point<br/>(src/cli.ts)<br/>Commander.js Interface"]
+    MAIN["Main Generator<br/>(src/generator.ts)<br/>Orchestrates the generation flow"]
+    PARSER["Swagger Parser<br/>(parser.ts)"]
+    UTILS["Utilities<br/>(utils.ts)"]
+    WRITER["File Writer<br/>(file-writer.ts)"]
+    GENS["Code Generators<br/>(src/generators/)"]
+    DTO["DTO Generator"]
+    SERVICE["Service Generator"]
+    CONTROLLER["Controller Generator"]
+    MODULE["Module Generator"]
+    OUTPUT["Output Files<br/>(generated/)"]
+
+    CLI --> MAIN
+    MAIN --> PARSER
+    MAIN --> UTILS
+    MAIN --> WRITER
+    PARSER --> GENS
+    UTILS --> GENS
+    WRITER --> GENS
+    GENS --> DTO
+    GENS --> SERVICE
+    GENS --> CONTROLLER
+    GENS --> MODULE
+    DTO --> OUTPUT
+    SERVICE --> OUTPUT
+    CONTROLLER --> OUTPUT
+    MODULE --> OUTPUT
+
+    style CLI fill:#4FC3F7,stroke:#01579B,stroke-width:3px,color:#000
+    style MAIN fill:#FFB74D,stroke:#E65100,stroke-width:3px,color:#000
+    style GENS fill:#BA68C8,stroke:#4A148C,stroke-width:3px,color:#fff
+    style OUTPUT fill:#81C784,stroke:#1B5E20,stroke-width:3px,color:#000
 ```
 
 ## Data Flow
 
-```
-1. Input
-   └─> Swagger/OpenAPI File (JSON/YAML)
-
-2. Parsing
-   └─> SwaggerParser.validate()
-       └─> Validated SwaggerSpec object
-
-3. Analysis
-   ├─> Extract schemas (definitions/components.schemas)
-   ├─> Group endpoints by tags
-   └─> Resolve $ref references
-
-4. Generation (Parallel)
-   ├─> DTOs
-   │   └─> For each schema:
-   │       ├─> Generate class
-   │       ├─> Add @ApiProperty decorators
-   │       └─> Handle types, arrays, refs
-   │
-   ├─> Services
-   │   └─> For each tag:
-   │       ├─> Generate @Injectable class
-   │       ├─> Create method for each endpoint
-   │       └─> Add JSDoc comments
-   │
-   ├─> Controllers
-   │   └─> For each tag:
-   │       ├─> Generate @Controller class
-   │       ├─> Add HTTP method decorators
-   │       ├─> Add @ApiTags, @ApiOperation
-   │       └─> Wire to service methods
-   │
-   └─> Modules
-       └─> For each tag:
-           ├─> Generate @Module class
-           ├─> Import controller & service
-           └─> Configure providers/exports
-
-5. Output
-   └─> Write TypeScript files to disk
+```mermaid
+graph LR
+    INPUT["1. Input<br/>Swagger/OpenAPI File<br/>(JSON/YAML)"]
+    PARSE["2. Parsing<br/>SwaggerParser.validate()<br/>→ Validated SwaggerSpec"]
+    ANALYZE["3. Analysis"]
+    SCHEMAS["Extract schemas<br/>(definitions/components)"]
+    TAGS["Group endpoints<br/>by tags"]
+    REFS["Resolve $ref<br/>references"]
+    GEN["4. Generation<br/>(Parallel)"]
+    DTOS["DTOs<br/>• Generate class<br/>• @ApiProperty decorators<br/>• Handle types, arrays, refs"]
+    SERVICES["Services<br/>• @Injectable class<br/>• Methods per endpoint<br/>• JSDoc comments"]
+    CONTROLLERS["Controllers<br/>• @Controller class<br/>• HTTP decorators<br/>• @ApiTags, @ApiOperation"]
+    MODULES["Modules<br/>• @Module class<br/>• Import controller & service<br/>• Configure providers"]
+    OUTPUT["5. Output<br/>Write TypeScript files<br/>to disk"]
+
+    INPUT --> PARSE
+    PARSE --> ANALYZE
+    ANALYZE --> SCHEMAS
+    ANALYZE --> TAGS
+    ANALYZE --> REFS
+    SCHEMAS --> GEN
+    TAGS --> GEN
+    REFS --> GEN
+    GEN --> DTOS
+    GEN --> SERVICES
+    GEN --> CONTROLLERS
+    GEN --> MODULES
+    DTOS --> OUTPUT
+    SERVICES --> OUTPUT
+    CONTROLLERS --> OUTPUT
+    MODULES --> OUTPUT
+
+    style INPUT fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style PARSE fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style ANALYZE fill:#AB47BC,stroke:#4A148C,stroke-width:2px,color:#fff
+    style GEN fill:#EC407A,stroke:#880E4F,stroke-width:2px,color:#fff
+    style OUTPUT fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
 ```
 
 ## Naming Convention Flow
 
-```
-Input: "/api/v1/user-profiles/{userId}"
-
-┌──────────────────────────────────────┐
-│     Path Analysis                     │
-├──────────────────────────────────────┤
-│ Extract tag: "user-profiles"         │
-│ Extract params: ["userId"]           │
-└───────────┬──────────────────────────┘
-            │
-            ▼
-┌──────────────────────────────────────┐
-│    Name Transformations               │
-├──────────────────────────────────────┤
-│ PascalCase: "UserProfiles"           │
-│   ├─> UserProfilesService            │
-│   ├─> UserProfilesController         │
-│   ├─> UserProfilesModule             │
-│   └─> UserProfileDto                 │
-│                                       │
-│ camelCase: "userProfiles"            │
-│   └─> userProfilesService (property) │
-│                                       │
-│ kebab-case: "user-profiles"          │
-│   ├─> user-profiles.service.ts       │
-│   ├─> user-profiles.controller.ts    │
-│   └─> user-profiles.module.ts        │
-└───────────────────────────────────────┘
+```mermaid
+graph TD
+    INPUT["Input Path<br/>/api/v1/user-profiles/{userId}"]
+    ANALYZE["Path Analysis<br/>• Extract tag: 'user-profiles'<br/>• Extract params: ['userId']"]
+    TRANSFORM["Name Transformations"]
+    PASCAL["PascalCase: 'UserProfiles'"]
+    CAMEL["camelCase: 'userProfiles'"]
+    KEBAB["kebab-case: 'user-profiles'"]
+    
+    PS1["UserProfilesService"]
+    PS2["UserProfilesController"]
+    PS3["UserProfilesModule"]
+    PS4["UserProfileDto"]
+    
+    CS1["userProfilesService<br/>(property)"]
+    
+    KS1["user-profiles.service.ts"]
+    KS2["user-profiles.controller.ts"]
+    KS3["user-profiles.module.ts"]
+
+    INPUT --> ANALYZE
+    ANALYZE --> TRANSFORM
+    TRANSFORM --> PASCAL
+    TRANSFORM --> CAMEL
+    TRANSFORM --> KEBAB
+    
+    PASCAL --> PS1
+    PASCAL --> PS2
+    PASCAL --> PS3
+    PASCAL --> PS4
+    
+    CAMEL --> CS1
+    
+    KEBAB --> KS1
+    KEBAB --> KS2
+    KEBAB --> KS3
+
+    style INPUT fill:#29B6F6,stroke:#01579B,stroke-width:2px,color:#000
+    style ANALYZE fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TRANSFORM fill:#AB47BC,stroke:#4A148C,stroke-width:2px,color:#fff
+    style PASCAL fill:#EF5350,stroke:#B71C1C,stroke-width:2px,color:#fff
+    style CAMEL fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style KEBAB fill:#FFEE58,stroke:#F57F17,stroke-width:2px,color:#000
 ```
 
 ## Type Mapping
 
-```
-Swagger Type         TypeScript Type       Decorator Type
-─────────────────────────────────────────────────────────
-string            -> string             -> type: String
-integer           -> number             -> type: Number
-number            -> number             -> type: Number
-boolean           -> boolean            -> type: Boolean
-array             -> T[]                -> isArray: true
-object            -> Record<string,any> -> type: Object
-string(date)      -> Date               -> type: Date
-string(date-time) -> Date               -> type: Date
-$ref              -> ClassName          -> type: () => ClassName
-enum              -> string             -> enum: [values]
+```mermaid
+graph LR
+    subgraph "Swagger Types"
+        ST1["string"]
+        ST2["integer"]
+        ST3["number"]
+        ST4["boolean"]
+        ST5["array"]
+        ST6["object"]
+        ST7["string(date)"]
+        ST8["string(date-time)"]
+        ST9["$ref"]
+        ST10["enum"]
+    end
+    
+    subgraph "TypeScript Types"
+        TS1["string"]
+        TS2["number"]
+        TS3["number"]
+        TS4["boolean"]
+        TS5["T[]"]
+        TS6["Record&lt;string,any&gt;"]
+        TS7["Date"]
+        TS8["Date"]
+        TS9["ClassName"]
+        TS10["string"]
+    end
+    
+    subgraph "Decorator Types"
+        DT1["type: String"]
+        DT2["type: Number"]
+        DT3["type: Number"]
+        DT4["type: Boolean"]
+        DT5["isArray: true"]
+        DT6["type: Object"]
+        DT7["type: Date"]
+        DT8["type: Date"]
+        DT9["type: () => ClassName"]
+        DT10["enum: [values]"]
+    end
+    
+    ST1 --> TS1 --> DT1
+    ST2 --> TS2 --> DT2
+    ST3 --> TS3 --> DT3
+    ST4 --> TS4 --> DT4
+    ST5 --> TS5 --> DT5
+    ST6 --> TS6 --> DT6
+    ST7 --> TS7 --> DT7
+    ST8 --> TS8 --> DT8
+    ST9 --> TS9 --> DT9
+    ST10 --> TS10 --> DT10
+    
+    style ST1 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST2 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST3 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST4 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST5 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST6 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST7 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST8 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST9 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style ST10 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    
+    style TS1 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS2 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS3 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS4 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS5 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS6 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS7 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS8 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS9 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style TS10 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    
+    style DT1 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT2 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT3 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT4 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT5 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT6 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT7 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT8 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT9 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style DT10 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
 ```
 
 ## Generation Workflow Example
 
-```
-Step 1: Parse Swagger
-   Input: example-swagger.json
-   Output: SwaggerSpec object
-
-Step 2: Extract Schemas
-   Found: User, CreateUserDto, UpdateUserDto, Post, CreatePostDto
-
-Step 3: Group Endpoints
-   Tags:
-   ├─> users: [GET /users, POST /users, GET /users/{id}, ...]
-   └─> posts: [GET /posts, POST /posts]
-
-Step 4: Generate DTOs
-   ├─> user.dto.ts
-   ├─> create-user-dto.dto.ts
-   ├─> update-user-dto.dto.ts
-   ├─> post.dto.ts
-   └─> create-post-dto.dto.ts
-
-Step 5: Generate Services
-   ├─> users.service.ts
-   │   Methods: getUsers(), createUser(), getUserById(), ...
-   └─> posts.service.ts
-       Methods: getPosts(), createPost()
-
-Step 6: Generate Controllers
-   ├─> users.controller.ts
-   │   Routes: @Get(''), @Post(''), @Get(':id'), ...
-   └─> posts.controller.ts
-       Routes: @Get(''), @Post('')
-
-Step 7: Generate Modules
-   ├─> users.module.ts
-   ├─> posts.module.ts
-   └─> app.module.ts (imports both)
-
-Step 8: Generate Index
-   └─> index.ts (exports all)
-
-Done! ✅
+```mermaid
+graph TD
+    STEP1["Step 1: Parse Swagger<br/>Input: example-swagger.json<br/>Output: SwaggerSpec object"]
+    STEP2["Step 2: Extract Schemas<br/>Found: User, CreateUserDto,<br/>UpdateUserDto, Post, CreatePostDto"]
+    STEP3["Step 3: Group Endpoints<br/>Tags:<br/>• users: GET /users, POST /users, GET /users/{id}<br/>• posts: GET /posts, POST /posts"]
+    STEP4["Step 4: Generate DTOs"]
+    STEP5["Step 5: Generate Services"]
+    STEP6["Step 6: Generate Controllers"]
+    STEP7["Step 7: Generate Modules"]
+    STEP8["Step 8: Generate Index"]
+    DONE["✅ Done!"]
+    
+    DTO1["user.dto.ts"]
+    DTO2["create-user-dto.dto.ts"]
+    DTO3["update-user-dto.dto.ts"]
+    DTO4["post.dto.ts"]
+    DTO5["create-post-dto.dto.ts"]
+    
+    SVC1["users.service.ts<br/>Methods: getUsers(),<br/>createUser(), getUserById()"]
+    SVC2["posts.service.ts<br/>Methods: getPosts(),<br/>createPost()"]
+    
+    CTL1["users.controller.ts<br/>Routes: @Get(''),<br/>@Post(''), @Get(':id')"]
+    CTL2["posts.controller.ts<br/>Routes: @Get(''),<br/>@Post('')"]
+    
+    MOD1["users.module.ts"]
+    MOD2["posts.module.ts"]
+    MOD3["app.module.ts<br/>(imports both)"]
+    
+    IDX["index.ts<br/>(exports all)"]
+
+    STEP1 --> STEP2
+    STEP2 --> STEP3
+    STEP3 --> STEP4
+    STEP4 --> DTO1 & DTO2 & DTO3 & DTO4 & DTO5
+    DTO1 & DTO2 & DTO3 & DTO4 & DTO5 --> STEP5
+    STEP5 --> SVC1 & SVC2
+    SVC1 & SVC2 --> STEP6
+    STEP6 --> CTL1 & CTL2
+    CTL1 & CTL2 --> STEP7
+    STEP7 --> MOD1 & MOD2 & MOD3
+    MOD1 & MOD2 & MOD3 --> STEP8
+    STEP8 --> IDX
+    IDX --> DONE
+
+    style STEP1 fill:#42A5F5,stroke:#0D47A1,stroke-width:2px,color:#fff
+    style STEP2 fill:#AB47BC,stroke:#4A148C,stroke-width:2px,color:#fff
+    style STEP3 fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000
+    style STEP4 fill:#EC407A,stroke:#880E4F,stroke-width:2px,color:#fff
+    style STEP5 fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#000
+    style STEP6 fill:#FFEE58,stroke:#F57F17,stroke-width:2px,color:#000
+    style STEP7 fill:#26A69A,stroke:#00695C,stroke-width:2px,color:#fff
+    style STEP8 fill:#FF7043,stroke:#BF360C,stroke-width:2px,color:#fff
+    style DONE fill:#4CAF50,stroke:#1B5E20,stroke-width:4px,color:#fff
 ```
 
 ## File Organization