# mkon/openapi_contracts architecture

> Architecture diagram of the GitHub repository mkon/openapi_contracts, 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/mkon/openapi_contracts
- Repository: https://github.com/mkon/openapi_contracts

## Overview

##### Project Type and Purpose
- This is a Ruby gem focused on using OpenAPI documentation as an API contract.
- It is meant to work within applications (especially Rails apps) to verify that API requests and responses adhere to the contract defined in an OpenAPI schema.
- It integrates with RSpec by providing matchers that assert responses against the OpenAPI document.
- Additionally, it supplies coverage reporting to indicate how thoroughly the API endpoints are tested.

##### File Structure
- Top-level directories include:
- “lib” where the core Ruby modules reside.
- “spec” with fixtures, test specs, and configurations for RSpec.
- “bin” contains executables (like build, console, release, etc.) for gem management.
- Test/helper directories (e.g., “spec/support”) for test setup.
- The “lib/openapi_contracts” directory is further subdivided into components like:
- “doc” which deals with OpenAPI document processing (headers, operation, parameters, paths, etc.).
- “coverage” which handles reporting and storing test coverage for API endpoints.
- “parser” to process and transform the OpenAPI file(s).
- “validators” to compare API responses (and optionally requests) against the OpenAPI definitions.
- Other supporting files such as “operation_router” and a helper module.
- Notice presence of RSpec matcher files and integration tests inside “spec” that validate the system’s functionality.

##### README for Additional Insights
- The README clearly explains that the gem:
- Parses an OpenAPI document, usually stored in “spec/fixtures/openapi/…”.
- Provides RSpec matchers (e.g., match_openapi_doc) for validating HTTP requests/responses.
- Validates different aspects (headers, http status, body, request body, parameters, etc.) by using json_schemer.
- Supports coverage reporting and merging of reports, which is an important part of the system.
- The operational workflow implies that a parsed document (using OpenapiContracts::Doc.parse) is used as a basis for all validation steps.

- Main Components to Include:
- OpenAPI Document Parser: Represents the component (lib/openapi_contracts/parser) that transforms raw OpenAPI YAML files into a structured format for further use.
- API Documentation Component: (lib/openapi_contracts/doc) handling representation and abstraction of API operations, paths, parameters, headers, etc.
- Validator/Matcher Component: (lib/openapi_contracts/validators and lib/openapi_contracts/match.rb) that compares actual responses (and optionally requests) from tests against the schema.
- Operation Router: (lib/openapi_contracts/operation_router) maps incoming requests (identified by method and path) to the correct documentation definitions.
- Coverage Reporting: (lib/openapi_contracts/coverage) stores and generates reports on which endpoints or responses have been validated.
- RSpec Integration: A connector layer where the gem’s matchers (for example match_openapi_doc) integrate with RSpec, using hooks like before(:suite) and after(:suite) to set up and report test coverage.
- Relationships and Interactions:
- The RSpec tests begin by invoking the Parser to load the OpenAPI document.
- The parsed document is represented in the documentation component.
- When a test executes, the Validator/Matcher component uses the API Documentation to validate the HTTP response.
- The Operation Router helps resolve dynamic paths to their schema definition.
- Throughout tests, coverage information is collected and later consolidated by the Coverage module.
- Architectural Patterns and Design Principles:
- Separation of Concerns: Each module (parsing, documenting, validating, and reporting) has a dedicated responsibility.
- Extensibility: The modular design (with separate components for operations like headers, parameters, etc.) allows for future enhancements such as validating Webmock stubs.
- Integration with external tools: Leveraging RSpec and json_schemer for validation.
- Technologies and Frameworks:
- Ruby language (with emphasis on gem-based development).
- RSpec for testing and matchers.
- JSON Schema validation tools (json_schemer) for schema checks.
- CI/CD integration (as seen by the .github directory and workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "RSpect Integration Layer"
        RSpec["RSpec Integration"]:::rspec
    end

    subgraph "Core Library Components"
        Parser["OpenAPI Document Parser"]:::parser
        Documentation["API Documentation Component"]:::documentation
        Validator["Validator & Matcher Component"]:::validator
        Router["Operation Router"]:::router
        Coverage["Coverage Reporter"]:::coverage
    end

    %% Connections
    RSpec -->|"initiates"| Parser
    Parser -->|"parsesTo"| Documentation
    Documentation -->|"suppliesSchemaTo"| Validator
    Documentation -->|"resolvesEndpointsFor"| Router
    Validator -->|"reportsOutcomeTo"| Coverage

    %% Click Events for OpenAPI Document Parser
    click Parser "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/parser.rb"
    click Parser "https://github.com/mkon/openapi_contracts/tree/main/lib/openapi_contracts/parser/transformers"

    %% Click Events for API Documentation Component
    click Documentation "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/doc.rb"
    click Documentation "https://github.com/mkon/openapi_contracts/tree/main/lib/openapi_contracts/doc"

    %% Click Events for Validator & Matcher Component
    click Validator "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/validators.rb"
    click Validator "https://github.com/mkon/openapi_contracts/tree/main/lib/openapi_contracts/validators"
    click Validator "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/match.rb"

    %% Click Event for Operation Router
    click Router "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/operation_router.rb"

    %% Click Events for Coverage Reporter
    click Coverage "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/coverage.rb"
    click Coverage "https://github.com/mkon/openapi_contracts/tree/main/lib/openapi_contracts/coverage"
    click Coverage "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/coverage/report.rb"
    click Coverage "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/coverage/store.rb"

    %% Click Events for RSpec Integration
    click RSpec "https://github.com/mkon/openapi_contracts/blob/main/lib/openapi_contracts/rspec.rb"
    click RSpec "https://github.com/mkon/openapi_contracts/tree/main/spec/integration"
    click RSpec "https://github.com/mkon/openapi_contracts/blob/main/spec/integration/rspec_spec.rb"

    %% Styles
    classDef parser fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef documentation fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef validator fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef router fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef coverage fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef rspec fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
```
