🏗️ OpenAPI Clean Architecture Generator | Contributor Wiki

Welcome to the internal development wiki. This project is designed to bridge the gap between OpenAPI specifications and Clean Architecture in Angular environments. As a contributor, your mission is to maintain the generator's core logic, refine Mustache templates, and ensure the generated code adheres to strict architectural boundaries.

🎯 Project Mission

To provide an opinionated yet flexible generator that enforces Separation of Concerns. We aim to make Angular applications easier to test and scale by completely decoupling the Domain (Business Logic) from the Data (Infrastructure/HTTP).

🛠️ Contributor Quick Start

If you are looking to modify the generator or add new features, follow these steps:

1. Development Environment

Clone the repository and install the core toolset:

git clone <repo-url>

npm install

npm run setup (Validates openapi-generator-cli and local environment)

2. Project Structure

Understanding where to apply changes:

templates/: The core engine. Contains .mustache files that define how the Angular code is written.

3. Testing Changes

To test template modifications without polluting your project, always use the development script with a sample schema:

npm run generate:dev -- -i swagger.yaml --dry-run

📂 Architecture Overview (The "Clean" Blueprint)

All contributions must respect the following layer boundaries to prevent circular dependencies:

Layer	Responsibility	Contributor Focus
Domain	Business Logic	Ensure interfaces and use-cases remain framework-agnostic.
Data	Infrastructure	Maintain DTO-to-Entity mapping logic and API implementations.
DI	Dependency Injection	Keep Angular `InjectionToken` and `Provider` logic up to date (e.g., `inject()`).
Entities	Models	Manage the core domain models used across the entire app.

🔧 Core Areas for Contribution

📄 Template Engineering (`/templates`)

This is where 90% of the logic lives. If we need to support new Angular features (like Signals or Standalone Components), we update these Mustache files.

api.repository.impl.mustache: Handles the HTTP layer logic.
mapper.mustache: Ensures Data Transfer Objects (DTOs) are correctly converted to Domain Entities.

⚙️ CLI Orchestration

The internal engine reads the OpenAPI output and distributes files into the Clean Architecture folders. We are constantly looking to optimize the generation-report.json and improve the CLI's developer experience (DX).

📜 Development Guidelines

Strict Typing: Any logic added to the generator must be fully typed in TypeScript.
Framework Alignment: Ensure generated code follows the latest Angular style guides (Angular 17+ focus).
No Logic in Templates: Keep .mustache files as declarative as possible. Move complex logic to the generator's TS source.
Dry-Run Verification: Never submit a PR without verifying the generated output folder structure.

🐛 Reporting & Feedback

Bug in Generated Code: Provide the specific swagger.yaml snippet that causes the issue.
Feature Request: Describe the desired Clean Architecture folder structure and provide an example of the expected .ts output.

💡 Contributor Note: This tool assumes the consumer uses the inject() function. Avoid adding traditional constructor-based DI to the templates unless explicitly required for backward compatibility.