# carapacik/swagger_parser architecture

> Architecture diagram of the GitHub repository carapacik/swagger_parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carapacik/swagger_parser
- Repository: https://github.com/carapacik/swagger_parser

## Overview

##### Main components
- Parser Module: This includes all components under swagger_parser/lib/src/parser. It is responsible for reading OpenAPI definitions (JSON/YAML), handling parsing errors (with exceptions like OpenApiParserException), correcting improper definitions through the “corrector”, and building universal model representations (universal_data_class, universal_enum_class, etc.).
- Generator Module: This is found under swagger_parser/lib/src/generator. It covers everything from generator configurations (GeneratorConfig), the main generation process (GeneratorProcessor, FillController), and a plethora of code templates for both Dart and Kotlin (e.g., dart_retrofit_client_template, kotlin_retrofit_client_template). This module is in charge of taking the parsed models and producing language-specific source files.
- Configuration Component: Look into the “config” directories under both parser and generator sections. This module handles configuration files and processing (for example, swp_config.dart, config_processor.dart) and ensures the tool respects user preferences and generation rules.
- Utilities & Core Support: This includes file I/O utilities (found under swagger_parser/lib/src/utils/file and io_file.dart) and various helper functions (like type_utils, case_utils) that assist both the parser and generator.
- Test & Validation: A vast number of end-to-end tests, schema examples, and even workflow configurations under .github/workflows indicate strong CI integration. This component shows that test cases and sample OpenAPI files are used to validate both parsing and generation functionalities.
- Web Interface (Optional/Additional Frontend): In the “swagger_parser_pages” directory, there is a separate Dart-based front end that leverages the core functionality to provide a user interface. It includes content modules, utilities, and web assets.

##### Relationships and interactions
- The Parser Module is the entry point for OpenAPI definition processing. It takes definition files (or links) as input, validates them using configuration and utility functions, and outputs processed universal models.
- The Generator Module then takes these universal models and, using language-specific templates and configurations, produces REST client code and data classes. This can involve multiple passes – for instance, a first pass to fill in controllers and a second to generate the final files.
- The Config Component sits underneath both the Parser and Generator and provides runtime configuration parameters.
- The Utility Components (file I/O and output utilities) serve both modules, ensuring that reading the source API definitions and writing out generated files are handled correctly.
- The test and workflow components wrap around all these modules to ensure quality and integration.
- The Web Interface, if part of the deployment, will interact with these core services to provide a GUI for users to experiment with or initiate the generation process.

##### Architectural patterns and design principles
- Separation of Concerns: The code is clearly divided into discrete modules for parsing, generation, configuration, and utilities.
- Template-Driven Code Generation: The generator uses a set of pre-defined templates for different languages, ensuring flexibility and extensibility.
- Modular Test-Driven Approach: Extensive test directories indicate a focus on quality and validating modular components using end-to-end tests.
- Support for Multiple Languages and Serializers: Built-in support for both Dart and Kotlin with their specific serialization strategies shows a layered abstraction to cater polymorphically to different targets.

##### Relevant technologies, frameworks, or libraries
- Dart is the primary language; the project is structured as a Dart package.
- For Dart serialization: json_serializable, freezed, dart_mappable.
- For Kotlin support: moshi, retrofit.
- GitHub workflows and CI tools are employed for continuous testing.
- For web interface: Standard Dart web packages are used, as seen in the “swagger_parser_pages” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("OpenAPI Definition Input"):::external
    A -->|"input"| B("Parser Module"):::core

    subgraph "Configuration Component"
        C1("Parser Configuration"):::core
        C2("Generator Configuration"):::core
        C3("Shared Configuration"):::core
    end
    C1 -->|"config"| B
    C3 -->|"shared config"| B

    subgraph "Utilities & Core Support"
        U1("General Utilities"):::utility
        U2("File I/O Utilities"):::utility
        U3("Output Utilities"):::utility
        U4("Parser Helper Functions"):::utility
    end
    U1 --- B
    U2 --- B
    U3 --- B
    U4 --- B

    B -->|"parsed models"| E("Parsed Universal Models"):::core

    subgraph "Generator Flow"
        C2 -->|"config"| F("Generator Module"):::core
        C3 -->|"shared config"| F
        E -->|"pass models"| F
        U1 --- F
        U2 --- F
        U3 --- F
        U4 --- F
        I("Web Interface"):::external
        I -->|"triggers"| F
        F -->|"generates"| G("Generated REST Client Code"):::core
    end

    H("Test & Validation"):::external
    H -->|"validates"| B
    H -->|"validates"| F

    %% Click Events
    click B "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/parser"
    click F "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/generator"
    click C1 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/parser/config"
    click C2 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/generator/config"
    click C3 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/config"
    click U1 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/utils"
    click U2 "https://github.com/carapacik/swagger_parser/blob/main/swagger_parser/lib/src/utils/file/io_file.dart"
    click U3 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/utils/output"
    click U4 "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/lib/src/parser/utils"
    click H "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser/test"
    click I "https://github.com/carapacik/swagger_parser/tree/main/swagger_parser_pages"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef utility fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
