# pb33f/libopenapi architecture

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

- Interactive diagram: https://gitdiagram.com/pb33f/libopenapi
- Repository: https://github.com/pb33f/libopenapi

## Overview

- Document/Input Loader & Parser: This is where a raw OpenAPI (or Swagger) spec is received (see document.go and related test files). It serves as the entry point that reads and converts the spec into an in-memory representation.
- Data Model Layer:
- High-Level Models (located in datamodel/high): Encapsulates rich, validated API constructs including operations, paths, schemas, components (for both OpenAPI 2, 3, and 3.1), with clear separation into sub-packages (e.g., base types, v2, v3).
- Low-Level Models (located in datamodel/low): Provides a lower abstraction that supports extraction and manipulation. The separation into “high” and “low” modules suggests a two-tier abstraction where the lower layer is responsible for raw parsing/translation and the higher layer for fully resolved objects.
- Indexing/Reference Resolution:
- This is represented by the “index” package. Components here (cache, resolver, rolodex, search_index, etc.) handle caching, looking up references, resolving circular references, and mapping nodes across the document.
- Bundling Module:
- Found under the “bundler” folder, this component is responsible for aggregating or bundling external and remote references, likely turning a multi-file or distributed specification into a unified document.
- Diff/What Changed Engine:
- The “what-changed” directory contains packages that compare API specifications. It uses its own data models and utility functions (like the “change_types”, “comparison_functions”, and “reports”) to report breaking changes.
- Renderer/Mock Generator:
- The “renderer” package contains modules for generating mock examples and rendering output based on the API’s schema.
- Utility Libraries:
- Supporting packages such as “json”, “orderedmap”, and “utils” provide essential helper functions for JSON manipulation, maintaining ordered maps, error unwrapping, and type-checking.
- Test Specs and Examples:
- The “test_specs” folder provides a variety of real-world example files that the library uses to test its functionality, demonstrating integration for different OpenAPI versions and structures.

##### Architectural patterns and notes
- Layered approach – with separation into high-level business (fully resolved, validated models) versus low-level raw parsing logic.
- That modularity is a design principle. Each package (bundler, index, renderer, what-changed) is largely decoupled and can be thought of as a micro-library cooperating with the others.
- The usage of utility libraries (orderedmap, json) and well-defined APIs is crucial for the extensibility and robustness of the system.
- That testing is thorough: many packages have accompanying *_test.go files and there is a strong emphasis on integration testing given the diverse test_specs provided.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Entry
    DOC["Document Loader/Parser"]:::input

    %% Data Modeling Layer Subgraph
    subgraph "Data Modeling Layer"
        D_HIGH["High-Level Models"]:::input
        D_LOW["Low-Level Models"]:::input
    end

    %% Core Business Modules
    IDX["Index & Resolver Module"]:::core
    BUNDLER["Bundler Module"]:::core
    RENDERER["Renderer/Mock Generator Module"]:::core
    DIFF["Diff/What Changed Module"]:::core

    %% Supporting Modules Subgraph
    subgraph "Supporting Modules"
        UTIL_JSON["JSON Library"]:::utility
        UTIL_OM["Ordered Map Library"]:::utility
        UTIL_UTILS["Utils Library"]:::utility
        CICD["CI/CD & Testing"]:::support
        TESTS["Test Specs & Examples"]:::support
    end

    %% Data Flow Arrows
    DOC -->|"transforms"| D_HIGH
    DOC -->|"transforms"| D_LOW

    D_HIGH -->|"builds"| IDX
    D_LOW  -->|"builds"| IDX

    D_HIGH -->|"aggregates"| BUNDLER
    D_LOW  -->|"aggregates"| BUNDLER

    D_HIGH -->|"renders"| RENDERER
    D_LOW  -->|"renders"| RENDERER

    D_HIGH -->|"compares"| DIFF
    D_LOW  -->|"compares"| DIFF

    %% Dashed dependencies from Diff module
    DIFF ---|"depends_on"| D_HIGH
    DIFF ---|"depends_on"| IDX

    %% Utility Support Dotted Arrows
    UTIL_JSON ---|"supports"| DOC
    UTIL_OM   ---|"supports"| D_HIGH
    UTIL_UTILS ---|"supports"| D_LOW
    UTIL_JSON ---|"supports"| IDX
    UTIL_OM   ---|"supports"| BUNDLER
    UTIL_UTILS ---|"supports"| RENDERER
    UTIL_JSON ---|"supports"| DIFF

    %% CI/CD and Test Specs supporting overall process
    CICD ---|"validates"| DOC
    TESTS ---|"verifies"| D_HIGH
    TESTS ---|"verifies"| BUNDLER
    TESTS ---|"verifies"| RENDERER
    TESTS ---|"verifies"| DIFF

    %% Click Events
    click DOC "https://github.com/pb33f/libopenapi/blob/main/document.go"
    click D_HIGH "https://github.com/pb33f/libopenapi/tree/main/datamodel/high"
    click D_LOW "https://github.com/pb33f/libopenapi/tree/main/datamodel/low"
    click IDX "https://github.com/pb33f/libopenapi/tree/main/index"
    click BUNDLER "https://github.com/pb33f/libopenapi/tree/main/bundler"
    click RENDERER "https://github.com/pb33f/libopenapi/tree/main/renderer"
    click DIFF "https://github.com/pb33f/libopenapi/tree/main/what-changed"
    click UTIL_JSON "https://github.com/pb33f/libopenapi/blob/main/json/json.go"
    click UTIL_OM "https://github.com/pb33f/libopenapi/tree/main/orderedmap"
    click UTIL_UTILS "https://github.com/pb33f/libopenapi/tree/main/utils"
    click TESTS "https://github.com/pb33f/libopenapi/tree/main/test_specs"
    click CICD "https://github.com/pb33f/libopenapi/blob/main/.github"

    %% Styles
    classDef input fill:#a2d39c,stroke:#333,stroke-width:2px;
    classDef core fill:#a1c4fd,stroke:#333,stroke-width:2px;
    classDef support fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef utility fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
