@eqxjs/swagger-codegen 1.0.0-beta.0

package/ARCHITECTURE.md

@@ -0,0 +1,230 @@
+# Architecture & Workflow
+
+## 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/) │
+                  └────────────────┘
+```
+
+## 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
+```
+
+## 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        │
+└───────────────────────────────────────┘
+```
+
+## 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]
+```
+
+## 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! ✅
+```
+
+## File Organization
+
+```
+Project Root
+├── src/                    (Source code)
+│   ├── cli.ts             (Entry point)
+│   ├── generator.ts       (Main logic)
+│   ├── parser.ts          (Swagger parsing)
+│   ├── types.ts           (Type definitions)
+│   ├── utils.ts           (Helpers)
+│   ├── file-writer.ts     (File I/O)
+│   └── generators/
+│       ├── dto.generator.ts
+│       ├── service.generator.ts
+│       ├── controller.generator.ts
+│       └── module.generator.ts
+│
+├── dist/                   (Compiled JavaScript)
+│
+├── generated/              (Generated code output)
+│   ├── dtos/              (All DTOs)
+│   │   ├── *.dto.ts
+│   ├── 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
+│   └── index.ts
+│
+├── example-swagger.json    (Example input)
+├── package.json
+├── tsconfig.json
+├── README.md
+└── SUMMARY.md
+```
+
+## Key Design Patterns
+
+1. **Command Pattern**: CLI commands trigger specific actions
+2. **Strategy Pattern**: Different generators for different code types
+3. **Factory Pattern**: Dynamic creation of code based on schemas
+4. **Template Pattern**: Consistent structure for generated files
+5. **Builder Pattern**: Incremental construction of output code

package/FORMATS.md

@@ -0,0 +1,180 @@
+# Format Examples
+
+This project supports both JSON and YAML formats for Swagger/OpenAPI specifications.
+
+## File Format Comparison
+
+### JSON Format (`example-swagger.json`)
+
+**Advantages:**
+- Native JavaScript format
+- Easier to generate programmatically
+- Better IDE support in some cases
+- Stricter syntax (comma-separated)
+
+**Example:**
+```json
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "Example API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Get all users",
+        "responses": {
+          "200": {
+            "description": "Success"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### YAML Format (`example-swagger.yaml`)
+
+**Advantages:**
+- More human-readable
+- Less verbose (no quotes, commas, or braces)
+- Widely used in API specification
+- Better for hand-editing
+
+**Example:**
+```yaml
+swagger: '2.0'
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Get all users
+      responses:
+        '200':
+          description: Success
+```
+
+## Usage
+
+Both formats work identically with this CLI tool:
+
+```bash
+# Swagger 2.0 - JSON format
+npm run dev -- generate -i ./example-swagger.json -o ./generated
+
+# Swagger 2.0 - YAML format
+npm run dev -- generate -i ./example-swagger.yaml -o ./generated
+
+# OpenAPI 3.0 - JSON format
+npm run dev -- generate -i ./openapi3-example.json -o ./generated
+
+# OpenAPI 3.0 - YAML format
+npm run dev -- generate -i ./openapi3-example.yaml -o ./generated
+
+# YAML with .yml extension (also supported)
+npm run dev -- generate -i ./api-spec.yml -o ./generated
+```
+
+## OpenAPI 3.x Support
+
+The tool also supports OpenAPI 3.x specifications in both formats:
+
+### OpenAPI 3.x (JSON)
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Example API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Get all users",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/User"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+### OpenAPI 3.x (YAML)
+```yaml
+openapi: 3.0.0
+info:
+  title: Example API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Get all users
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+```
+
+## Key Differences: Swagger 2.0 vs OpenAPI 3.x
+
+### Schema Location
+- **Swagger 2.0**: `definitions`
+- **OpenAPI 3.x**: `components.schemas`
+
+### Request Body
+- **Swagger 2.0**: `parameters` with `in: "body"`
+- **OpenAPI 3.x**: `requestBody` with `content`
+
+### Response Content
+- **Swagger 2.0**: `schema` directly in response
+- **OpenAPI 3.x**: `content` -> `application/json` -> `schema`
+
+## Recommendation
+
+Choose the format that best fits your workflow:
+- Use **YAML** for hand-written specifications (more readable)
+- Use **JSON** for programmatically generated specs (easier to work with in code)
+
+The CLI tool handles both formats seamlessly with the same commands and produces identical output.