How enricodeleo/aquasdk works
Main Components
• CLI/Entry Point: The tool is intended to be run as a command-line utility. The entry point is exposed via commands like “generate-sdk” (invoked from the command line) that trigger the processing workflow.
• OpenAPI Specification Input: This is the input file (e.g., swagger.json) provided by the user. It is the starting point for the SDK generation process.
• Preprocessor (src/preprocessor.js): This component is responsible for reading and resolving any complexities in the OpenAPI spec (such as circular references or nested data structures) to prepare it for code generation.
• Generator (src/generator.js): After preprocessing, this component coordinates the code generation. It reads the preprocessed API definition and directs the generation process.
• Template Engine (src/templates folder): This includes the Handlebars templates (e.g., client.hbs, model.hbs, index.hbs, resource.hbs, readme.hbs, and additional utility templates) that define the structure of the generated SDK files.
• Utilities (src/templates/utils): Contains helper functions (like queryUtils.js) that support the template rendering or the generated SDK's functionality.
• Output SDK: The final output is a directory structure (for example, “./sdk”) containing the generated JavaScript files which realize the API methods, models, and chainable query methods for interacting with the API.
Mapping Relationships and Interactions
• The user supplies an OpenAPI JSON file as input.
• The CLI/Entry Point passes the specification to the Preprocessor.
• The Preprocessor cleans and augments the spec, passing the resulting data to the Generator.
• The Generator coordinates with the Template Engine to render the corresponding files (using the .hbs templates) for each model, method, and utility.
• The rendered output (JavaScript SDK components) is then written to the user-specified output directory.
Important Architectural Patterns and Design Principles
• Separation of Concerns: Different files (or modules) handle distinct responsibilities (e.g., input processing, pre-processing of spec data, code generation, and template rendering).
• Pipeline Architecture: The process flows in stages—from receiving the OpenAPI spec to transforming it into a fully-functional SDK—allowing easier modifications or expansions at each stage.
• Template-Driven Code Generation: Use of Handlebars as a templating engine ensures a clean separation between the “logic” (data handling) and the “presentation” (generated code structure).
Relevant Technologies and Frameworks
• Node.js and JavaScript: The tool itself is built in JavaScript, utilizing Node.js.
• Handlebars: Employed for creating dynamic templates that generate the SDK source code.
• NPM and related configuration files (e.g., package.json, eslint.config.js): These facilitate package management, linting, and consistent coding standards.
• Git & GPL License: Indicating open-source collaboration and licensing terms.
What
• CLI/Command-Line Interface (Invokes generate-sdk command)
• Input Handler (Reads OpenAPI spec file)
• Preprocessor (src/preprocessor.js)
• Generator (src/generator.js)
• Template Engine (src/templates: list out client.hbs, model.hbs, etc.)
• Utility Helpers (src/templates/utils)
• Output (Generated SDK structure with chainable API method classes and configurations)
• Input → Preprocessor → Generator → Template Engine → Output.
• Processing modules (Preprocessor, Generator).
• Template files (grouped under one component).
• External elements (the original OpenAPI spec and the final generated SDK).