# syroegkin/swagger-markdown architecture

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

- Interactive diagram: https://gitdiagram.com/syroegkin/swagger-markdown
- Repository: https://github.com/syroegkin/swagger-markdown

## Overview

##### Project Type and Purpose
- swagger-markdown is a CLI tool written in TypeScript.
- Its main purpose is to convert Swagger (OpenAPI 2.0) YAML files into Markdown documentation.
- It focuses on parsing input files, handling version checks (swagger 2.0 only, with a forced flag for v3), and then generating the corresponding markdown output.

##### File Structure
- Top-Level Files and Directories:
- Configuration files (.circleci, .husky, eslint, etc.) indicate continuous integration, linting, and commit pre-checks.
- The README and examples directory showcase usage examples.
- The “src” folder holds the core source code with the CLI entry (src/swagger-markdown.ts) and other modules.
- Core Source Folders:
- The “src/lib” directory contains common utilities such as anchor creation, markdown processing (with submodules for handling markdown strings, tables, etc.), text escaping, and swagger document version detection.
- The “src/transformers” folder contains the heart of the processing logic that transforms the swagger YAML input: there’s a central document transformer (documentV2.ts) and a series of specialized transformer modules inside “src/transformers/v2” (for contact, dataTypes, definitions, external docs, info, license, etc.).
- Testing and Tooling:
- Jest is used for unit/integration tests (as indicated by files ending with .spec.ts).
- The package.json and related configuration files show that this is a Node.js project built to run as a CLI tool.

##### Main Components of the System (to be represented
- Command Line Interface (CLI):
- Represented by the entry point (src/swagger-markdown.ts) which handles parsing input arguments, flags (like --force-version), and coordinates file I/O.
- Input Layer:
- The component that reads the Swagger YAML file from disk.
- Error handling for unsupported Swagger versions (with a node pointing out the role of detectDocumentVersion.ts).
- Core Processing / Transformation Layer:
- Break this into sub-components:
▪ Validation & Version Detection: (src/lib/detectDocumentVersion.ts)
▪ Base Transformer: Processes the overall document structure (src/transformers/documentV2.ts).
▪ Modular Transformers: Several modules under “src/transformers/v2” process detailed sections such as:
- Info (info.ts)
- Definitions (definitions.ts, models/)
- Security (security.ts, securityDefinitions.ts)
- Paths, headers, parameters and more.
- Utilities: The “src/lib/markdown” modules create markdown snippets (anchors, tables, and text escapes) used by the transformers.
- Output Generation:
- Post transformation, the tool writes the generated markdown text to a file.
- Output file creation (with file naming based on the input swagger YAML name).

##### Relationships and Data Flow
- Next, the input data is passed to the Core Processing Layer.
- Data is first validated (ensure it is indeed swagger v2, or forced via the --force-version flag).
- The validated YAML is then parsed into an internal representation.
- The internal representation is then fed into the right transformer modules:
- Each transformer (for info, definitions, path parameters, etc.) generates a markdown segment.
- These segments are unified by the base transformer module.
- Finally, the Output Generator writes the combined markdown content to disk.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly separated into multiple transformer modules that each handle specific parts of the swagger spec.
- Single Responsibility: Each module (e.g., markdown formatting, text escaping, swagger document detection) has a distinct responsibility.
- Extensibility: The presence of a roadmap to support swagger v3 (and a flag-based override) indicates planning for future extensions.
- Separation of Concerns: The CLI, processing logic, utilities, and tests are well-separated in the file structure.

##### Technologies, Frameworks, and Libraries
- Language: TypeScript running on Node.js.
- Testing: Jest (as seen in numerous *.spec.ts files).
- Continuous Integration: CircleCI configuration is present.
- Linting and Standards: ESLint configuration, Husky hooks, and markdown linting are used to enforce code quality.
- Dependency Management: npm (via package.json).

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI & I/O Layer
    subgraph "CLI & I/O Layer"
        CLI["CLI Interface"]:::cli
        Output["Output Generator"]:::output
    end

    %% Input & Validation Layer
    subgraph "Input & Validation"
        Input["Input Reader"]:::validation
        Validator["Version Detection"]:::validation
    end

    %% Transformation Layer
    subgraph "Transformation Layer"
        CoreTransformer["Core Transformer"]:::transformer
        subgraph "Modular Transformers"
            Info["Info Transformer"]:::transformer
            Defs["Definitions Transformer"]:::transformer
            Contact["Contact Transformer"]:::transformer
            DataTypes["DataTypes Transformer"]:::transformer
            ExtDocs["ExternalDocs Transformer"]:::transformer
            License["License Transformer"]:::transformer
            Security["Security Transformer"]:::transformer
            Paths["Paths Transformer"]:::transformer
        end
    end

    %% Utilities Layer
    subgraph "Utilities"
        MDUtil["Markdown Utilities"]:::utility
        AnchorUtil["Anchor Generator"]:::utility
        TextEscape["Text Escaping"]:::utility
    end

    %% Data Flow
    CLI -->|"gets_input"| Input
    Input -->|"reads_YAML"| Validator
    Validator -->|"validates_version"| CoreTransformer
    CoreTransformer -->|"transforms"| Info
    CoreTransformer -->|"transforms"| Defs
    CoreTransformer -->|"transforms"| Contact
    CoreTransformer -->|"transforms"| DataTypes
    CoreTransformer -->|"transforms"| ExtDocs
    CoreTransformer -->|"transforms"| License
    CoreTransformer -->|"transforms"| Security
    CoreTransformer -->|"transforms"| Paths

    %% Utilities usage connections
    Info --- MDUtil
    Defs --- MDUtil
    Contact --- MDUtil
    DataTypes --- MDUtil
    ExtDocs --- MDUtil
    License --- MDUtil
    Security --- MDUtil
    Paths --- MDUtil
    MDUtil --- AnchorUtil
    MDUtil --- TextEscape

    %% Output Generation connections
    Info -->|"outputs"| Output
    Defs -->|"outputs"| Output
    Contact -->|"outputs"| Output
    DataTypes -->|"outputs"| Output
    ExtDocs -->|"outputs"| Output
    License -->|"outputs"| Output
    Security -->|"outputs"| Output
    Paths -->|"outputs"| Output
    MDUtil -->|"outputs"| Output
    CLI -->|"triggers_output"| Output

    %% Click Events
    click CLI "https://github.com/syroegkin/swagger-markdown/blob/master/src/swagger-markdown.ts"
    click Validator "https://github.com/syroegkin/swagger-markdown/blob/master/src/lib/detectDocumentVersion.ts"
    click CoreTransformer "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/documentV2.ts"
    click Info "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/info.ts"
    click Defs "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/definitions.ts"
    click Contact "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/contact.ts"
    click DataTypes "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/dataTypes.ts"
    click ExtDocs "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/externalDocs.ts"
    click License "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/license.ts"
    click Security "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/security.ts"
    click Paths "https://github.com/syroegkin/swagger-markdown/blob/master/src/transformers/v2/path.ts"
    click MDUtil "https://github.com/syroegkin/swagger-markdown/tree/master/src/lib/markdown/"
    click AnchorUtil "https://github.com/syroegkin/swagger-markdown/blob/master/src/lib/anchor.ts"
    click TextEscape "https://github.com/syroegkin/swagger-markdown/blob/master/src/lib/textEscape.ts"

    %% Class Definitions
    classDef cli fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef validation fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef transformer fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef utility fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef output fill:#f4a460,stroke:#333,stroke-width:2px;

    class CLI,Output cli;
    class Input,Validator validation;
    class CoreTransformer,Info,Defs,Contact,DataTypes,ExtDocs,License,Security,Paths transformer;
    class MDUtil,AnchorUtil,TextEscape utility;
```
