# exoego/rspec-openapi architecture

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

- Interactive diagram: https://gitdiagram.com/exoego/rspec-openapi
- Repository: https://github.com/exoego/rspec-openapi

## Overview

##### Main Components
- Core Library (located in lib/rspec/openapi):
- Components such as the OpenAPI schema builder, schema merger, schema cleaner, record builder/recorder, hash/key transformers, and shared/extractor hooks.
- Specific extractors for different frameworks (Rails, Rack, Hanami) visible under lib/rspec/openapi/extractors.
- RSpec hooks and integration code (for example, rspec_hooks.rb and shared_hooks.rb).

- Integration Points:
- RSpec integration (hooking into RSpec tests to capture API calls)
- Minitest support (configured through minitest_hooks.rb and examples in spec/minitest)
- User configuration (via module-level assignments in the README examples, supporting dynamic behavior like setting paths, titles, server details, etc.)

- Output Module:
- The component takes the captured request/response data and generates or updates the OpenAPI specification file (e.g. doc/openapi.yaml or doc/schema.json).

- Sample Applications:
- There are sample/test apps in spec/apps (for Hanami, Rails, and Roda) which illustrate how request specs are written across frameworks and how the gem integrates with them.

- CI/CD and Quality Tools:
- The project includes a .github directory with workflows for testing, RuboCop, and CodeQL analysis, ensuring code quality and security during the build process.

##### Relationships and Data Flow
- The process can be diagrammed as a pipeline:
- Start at the “Test Suite” (RSpec and Minitest tests written by the user) which make HTTP-like request calls against the sample or live API endpoints.
- These tests are instrumented by the gem’s integration hooks (e.g., rspec_hooks, minitest_hooks) that intercept calls and collect request/response details.
- Following extraction, the “Schema Builder/Merger” module assembles the OpenAPI specification. Modules like schema_builder, schema_merger, schema_sorter, and schema_cleaner work in a pipeline to aggregate and consolidate data—also preserving any manual modifications.
- The final output is written to a documentation file (doc/openapi.yaml or doc/schema.json), which can be used by documentation tools (Swagger UI, Redoc).

##### Architectural Patterns and Principles
- Modular design: Separating the extraction logic (framework-specific) from the core schema-building logic.
- Hook-based Integration: The gem “plugs into” test frameworks (using RSpec and Minitest hooks) to capture data automatically.
- Configurability: Users can customize various aspects (path, title, request/response headers, etc.) through a Ruby DSL. This dynamic configuration pipeline should be represented.
- Preservation of manual changes: The merging strategy ensures that manually modified parts of the schema are preserved.

##### Relevant Technologies & Frameworks
- Ruby and RSpec (core language/testing framework) along with Minitest.
- Specific web frameworks showcased in the samples (Rails, Hanami, Roda) – these are not part of the gem per se but demonstrate its integration.
- Continuous integration tools such as CodeQL, RuboCop, and GitHub Actions.

##### Elements
- Test Suites (RSpec/Minitest tests)
- Hook Layer (RSpec hooks, minitest hooks)
- Extractors (subcomponents for Rails, Hanami, Rack)
- Schema Builder/Merger (modules that construct and merge the OpenAPI specs)
- Output (the generated doc/openapi.yaml or doc/schema.json)
- Configuration/Customization (user settings that influence generation)
- CI/CD Workflows (GitHub Actions for testing, linting, security analysis)
- Core library components
- Integration modules (hooks/extractors)
- External interfaces or output (documentation file, external API documentation tools).
- Optionally, note the additional “sample apps” that demonstrate concrete usage scenarios.

## Diagram (Mermaid)

```mermaid
graph TD
    TTest["RSpec/Minitest Tests"]:::external
    TTest --> IHooks["Integration Hooks"]:::integration

    subgraph "Integration Hooks"
        I1["RSpec Hooks"]:::integration
        I2["Minitest Hooks"]:::integration
        I3["Shared Hooks"]:::integration
    end

    IHooks -->|"triggers"| Extractors["Extractors"]:::integration

    subgraph "Extractors"
        E1["Rails Extractor"]:::integration
        E2["Hanami Extractor"]:::integration
        E3["Rack Extractor"]:::integration
    end

    Extractors -->|"feeds"| SchemaProc["Schema Processing"]:::core

    subgraph "Schema Processing"
        S1["Schema Builder"]:::core
        S2["Schema Merger"]:::core
        S3["Schema Cleaner"]:::core
        S4["Schema Sorter"]:::core
        R1["Record Builder"]:::core
        R2["Result Recorder"]:::core
        U1["Hash Helper"]:::core
        U2["Key Transformer"]:::core
    end

    SchemaProc -->|"generates"| Output["Output: OpenAPI Spec File"]:::output

    Config["User Configuration"]:::config
    Config --- IHooks
    Config --- SchemaProc

    subgraph "Sample Applications"
        SA1["Hanami App Sample"]:::sample
        SA2["Rails App Sample"]:::sample
        SA3["Roda App Sample"]:::sample
    end

    TTest --- SA1
    TTest --- SA2
    TTest --- SA3

    Repo["Source Code Repository"]:::core
    Repo --> CICD["CI/CD Workflows"]:::cicd

    %% Click Events
    click S1 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/schema_builder.rb"
    click S2 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/schema_merger.rb"
    click S3 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/schema_cleaner.rb"
    click S4 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/schema_sorter.rb"
    click E1 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/extractors/rails.rb"
    click E2 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/extractors/hanami.rb"
    click E3 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/extractors/rack.rb"
    click I1 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/rspec_hooks.rb"
    click I2 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/minitest_hooks.rb"
    click I3 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/shared_hooks.rb"
    click R1 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/record_builder.rb"
    click R2 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/result_recorder.rb"
    click U1 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/hash_helper.rb"
    click U2 "https://github.com/exoego/rspec-openapi/blob/master/lib/rspec/openapi/key_transformer.rb"
    click SA1 "https://github.com/exoego/rspec-openapi/tree/master/spec/apps/hanami"
    click SA2 "https://github.com/exoego/rspec-openapi/tree/master/spec/apps/rails"
    click SA3 "https://github.com/exoego/rspec-openapi/tree/master/spec/apps/roda"
    click CICD "https://github.com/exoego/rspec-openapi/tree/master/.github/workflows"

    %% Styles
    classDef external fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef integration fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef core fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef config fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef output fill:#ede7f6,stroke:#5e35b1,stroke-width:2px;
    classDef sample fill:#f1f8e9,stroke:#558b2f,stroke-width:2px;
    classDef cicd fill:#ffebee,stroke:#c62828,stroke-width:2px;
```
