diff --git a/markdown/docs/tools/cli/architecture.md b/markdown/docs/tools/cli/architecture.md new file mode 100644 index 000000000000..81216dac8edb --- /dev/null +++ b/markdown/docs/tools/cli/architecture.md @@ -0,0 +1,98 @@ +--- +title: 'CLI Architecture' +weight: 40 +--- + +The AsyncAPI CLI uses oclif (Open CLI Framework) as its core framework, which enables developers to build powerful and scalable command-line applications. + +**Structure of the AsyncAPI CLI**: The CLI is primarily divided into two components: commands and the core part. + +1. **Command Component**: The commands include all the necessary functionalities that help developers interact with features like creating new AsyncAPI projects, validating AsyncAPI files, formatting AsyncAPI files, and more. +2. **Core Component**: The core part of the CLI contains various utilities that facilitate the efficient creation of new commands. + +--- + +### **Detailed Explanation of Key Directories in the CLI** + +#### **`src/commands/`** +- **Purpose:** Implements the CLI commands available to the user. +- **Subdirectories:** + - `config/`: Stores configuration-related files for commands. + - `generate/`: Generates typed models or other artifacts like clients, applications, or documentation using AsyncAPI Generator templates. + - **Files:** + - `fromTemplate.ts`: Contains logic for generating files using templates. + - `models.ts`: Defines the models used during generation. + - `new/`: Creates a new AsyncAPI file. + - **Files:** + - `file.ts`: Handles file creation logic. + - `glee.ts`: Related to Glee, a tool for event-driven microservices. + - `template.ts`: Manages templates for new projects. + - `start/`: Implements starting functionalities like launching a local server or studio. + - **Files:** + - `studio.ts`: Integrates with the AsyncAPI Studio. + +- **Standalone Files:** + - `bundle.ts`: Bundles one or multiple AsyncAPI documents and their references together. + - `convert.ts`: Converts AsyncAPI documents from older to newer versions or transforms OpenAPI/Postman-collection documents into AsyncAPI. + - `diff.ts`: Compares two AsyncAPI documents. + - `format.ts`: Converts AsyncAPI documents from any format to YAML, YML, or JSON. + - `optimize.ts`: Optimizes AsyncAPI documents for performance. + - `pretty.ts`: Beautifies the AsyncAPI spec file (indentation, styling) in place or outputs the formatted spec to a new file. + - `validate.ts`: Validates AsyncAPI documents for correctness. + +--- + +#### **`src/core/`** +- **Purpose:** Provides foundational components and utilities for the CLI. +- **Subdirectories:** + - `errors/`: Centralized error definitions. + - `flags/`: Defines CLI flags and their behavior. + - `hooks/`: Event hooks used for customization. + - `models/`: Core data models used across the application. + - `utils/`: Utility functions for common operations. + +- **Standalone Files:** + - `base.ts`: Base class or logic for CLI commands. + - `global.d.ts`: Global TypeScript definitions. + - `globals.ts`: Stores global variables and configurations. + - `parser.ts`: Parses AsyncAPI documents. + +--- + +#### **`test/`** +- **Purpose:** Implements the test suite for the CLI. +- **Subdirectories:** + - `fixtures/`: Contains mock data or files for testing. + - `hooks/`: Tests related to hooks. + - `integration/`: Integration tests to verify end-to-end functionality. + - `system/`: System-level tests. + - `unit/`: Unit tests for individual modules or functions. + +--- + +### **Use Cases** + +1. **Generate AsyncAPI Artifacts:** + - Use the `generate` command to create client/server code, documentation, or other artifacts based on AsyncAPI templates. + +2. **Create New Projects:** + - The `new` command helps users scaffold new AsyncAPI projects with predefined templates. + +3. **Validate AsyncAPI Documents:** + - The `validate` command ensures AsyncAPI documents conform to the specification. + +4. **Optimize and Format Documents:** + - The `optimize` and `pretty` commands provide tools for improving document readability and performance. + +5. **Compare Documents:** + - The `diff` command enables comparison between two AsyncAPI documents to track changes. + +6. **Integration with AsyncAPI Studio:** + - The `start` command integrates with the AsyncAPI Studio for editing and visualizing documents. + +7. **Convert Between Formats:** + - The `convert` command supports converting AsyncAPI documents between formats like YAML and JSON. + +--- + +This structure ensures the CLI is modular, scalable, and easy to maintain. Let me know if you need further clarification or additional details! \ No newline at end of file diff --git a/markdown/docs/tools/cli/context.md b/markdown/docs/tools/cli/context.md index 30803782e556..2a64fab21ef9 100644 --- a/markdown/docs/tools/cli/context.md +++ b/markdown/docs/tools/cli/context.md @@ -1,6 +1,6 @@ --- title: 'Context concept' -weight: 50 +weight: 60 --- ## Overview diff --git a/markdown/docs/tools/cli/metrics_collection.md b/markdown/docs/tools/cli/metrics_collection.md index cd9a4c6f7770..4df0dec069e9 100644 --- a/markdown/docs/tools/cli/metrics_collection.md +++ b/markdown/docs/tools/cli/metrics_collection.md @@ -1,6 +1,6 @@ --- title: 'Metrics Collection' -weight: 60 +weight: 70 --- # Metrics collection guideline diff --git a/markdown/docs/tools/cli/usage.md b/markdown/docs/tools/cli/usage.md index 09174c3e852a..5848de7aa2cc 100644 --- a/markdown/docs/tools/cli/usage.md +++ b/markdown/docs/tools/cli/usage.md @@ -1,6 +1,6 @@ --- title: 'Usage' -weight: 40 +weight: 50 ---