# codeasashu/openman architecture

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

- Interactive diagram: https://gitdiagram.com/codeasashu/openman
- Repository: https://github.com/codeasashu/openman

## Overview

##### Project Type and Purpose
- Openman is a command-line tool (and package) aimed at converting Postman JSON collections into OpenAPI specifications and generating mocked API responses.
- The tool is intended for developers wanting an automated way to migrate API documentation or generate mocks based on examples in their postman collections, while also offering flexibility (using an ignore file) to filter out unstable fields.

##### Analyzing the File Structure – Key Components Identified
- CLI Interface:
- openman/cli.py: Main entry point for handling CLI commands.
- This module interprets commands such as “convert” and “mock”.
- Parsing Module:
- openman/parser directory with files like collection.py, folder.py, request.py, requestitem.py, and response.py.
- These modules are responsible for extracting and parsing the structure of the Postman collection.
- Specification and Conversion:
- openman/schema_converter.py: Handles the transformation of parsed Postman data into the OpenAPI spec.
- openman/spec directory with submodules (collector, operation, plugins, spec) likely to encapsulate various aspects of building and validating the final specification.
- Mocking Component:
- openman/mock directory (with files fakemock_resolver.py and mock.py) contains functionality for generating mock responses based on the OpenAPI schema and provided examples.
- Utility and Error Handling:
- openman/errors.py and openman/utils.py manage errors and common tasks across modules.
- Testing and CI:
- The tests directory covers unit tests for CLI, parser modules, schema converter, and the spec submodules.
- CI and project configuration files (e.g., .github workflows, setup.py, etc.) are also part of the overall ecosystem.

- Main Components to Illustrate:
- CLI Entry Point: “openman/cli.py” which accepts user commands like “convert” and “mock”.
- Input File: The Postman JSON collection provided as input.
- Parser Layer: Comprising modules under “openman/parser/…” that read and interpret the collection structure (collections, folders, requests, responses).
- Schema Conversion Layer: “openman/schema_converter.py” along with logic in “openman/spec/…” to transform parsed data into a valid OpenAPI spec.
- Mocking Layer: “openman/mock/…” which takes the OpenAPI spec and uses it (along with provided postman examples) to generate mock responses.
- Optional Configuration: The ignore file (YAML) that influences schema conversion by specifying paths (using jsonpath-rw notation) that are to be filtered out.
- Utility/Error Handling Components that provide support and logging throughout.
- Testing & CI Infrastructure: Represented as separate validation components (indicating tests and workflows that ensure integrity).

- Relationships and Data Flow:
- Start at the CLI which receives user commands and file paths.
- Data flows from the input Postman collection to the Parser layer.
- Parsed data is then passed to the Schema Conversion layer to generate an OpenAPI spec.
- Optionally, the ignore file is consulted during conversion to omit specified fields.
- If “mock” is chosen, the spec is then forwarded to the Mocking layer to generate the appropriate responses based on input examples.
- Auxiliary modules like “utils” and “errors” support all these layers with common functionality.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project is clearly divided into distinct modules – parsing, conversion, and mock generation – ensuring each aspect does one thing well.
- Modularity: Use of submodules within “openman” (parser, spec, mock) reflects a modular design where functionality is encapsulated in its own component.
- CLI-Oriented Workflow: A command-line driven architecture where commands trigger different processing pipelines.
- Extensibility: The schema alteration using an ignore YAML file and pluggable components (as seen with spec/plugins.py) indicate a design made for extension and customization.

b. Input sources with two nodes: “Postman Collection JSON” and “Ignore YAML File (optional)”.
d. Parser to the “Schema Conversion Layer”, showing that the parsed data is sent to “schema_converter.py” along with components from “openman/spec”.
e. From this layer, split the data flow:
- One path illustrates the conversion output: “OpenAPI Spec (YAML/JSON)”.
- The second path (if the mock command is invoked) goes into the “Mocking Module” (openman/mock) that uses the converted spec and postman examples to produce responses.
f. Surround these components with a note that “Utils” and “Errors” modules support all layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Sources
    subgraph "Input Sources"
        A["Postman Collection JSON"]:::external
        B["Ignore YAML File (optional)"]:::external
    end

    %% Core Application Layers
    C["CLI Interface"]:::cli
    subgraph "Parser Layer"
        D["Postman Parser"]:::parser
    end

    subgraph "Schema Conversion Layer"
        E["Schema Converter"]:::convert
        F["Spec Builder"]:::convert
    end

    G["OpenAPI Spec (YAML/JSON)"]:::external

    subgraph "Mocking Layer"
        H["Mocking Module"]:::mock
    end

    %% Support Components
    subgraph "Support"
        U["Utils"]:::utility
        V["Errors"]:::utility
    end

    %% Testing and CI
    subgraph "Testing & CI"
        T["Tests"]:::test
        W["CI Workflows"]:::test
    end

    %% Data Flow
    A -->|"provides"| C
    B -->|"provides"| C
    C -->|"initiates"| D
    D -->|"parsedData"| E
    D -->|"parsedData"| F
    E -->|"produces"| G
    F -->|"augments"| G
    G -->|"if-mock-invoked"| H

    %% Support Links (dashed)
    C ---|"support"| U
    C ---|"support"| V
    D ---|"support"| U
    D ---|"support"| V
    E ---|"support"| U
    E ---|"support"| V
    F ---|"support"| U
    F ---|"support"| V
    H ---|"support"| U
    H ---|"support"| V

    %% Testing & CI Validation (dashed)
    C ---|"validated"| T
    D ---|"validated"| T
    E ---|"validated"| T
    F ---|"validated"| T
    H ---|"validated"| T
    C ---|"validated"| W
    D ---|"validated"| W
    E ---|"validated"| W
    F ---|"validated"| W
    H ---|"validated"| W

    %% Click Events
    click C "https://github.com/codeasashu/openman/blob/master/openman/cli.py"
    click D "https://github.com/codeasashu/openman/tree/master/openman/parser/"
    click E "https://github.com/codeasashu/openman/blob/master/openman/schema_converter.py"
    click F "https://github.com/codeasashu/openman/tree/master/openman/spec/"
    click H "https://github.com/codeasashu/openman/tree/master/openman/mock/"
    click U "https://github.com/codeasashu/openman/blob/master/openman/utils.py"
    click V "https://github.com/codeasashu/openman/blob/master/openman/errors.py"
    click T "https://github.com/codeasashu/openman/tree/master/tests/"
    click W "https://github.com/codeasashu/openman/tree/master/.github/workflows/"

    %% Styles
    classDef cli fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef parser fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef convert fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef mock fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef utility fill:#e0e0e0,stroke:#808080,stroke-width:2px;
    classDef test fill:#ffedcc,stroke:#cc9900,stroke-width:2px;
    classDef external fill:#d9e8fc,stroke:#1a73e8,stroke-width:2px;
```
