# eazybytes/openapi architecture

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

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

## Overview

##### Project Type and Purpose
- This repository is a multi-module demo/tutorial focusing on the OpenAPI Specification and Swagger tooling.
- It includes:
- A set of standalone OpenAPI YAML examples (openapi-yaml-examples)
- A static “Swagger UI” deployment (openapi-deployment) to host a chosen spec as documentation
- A Spring Boot REST API demo (springboot-openapi-demo) that uses springdoc-openapi to generate its own spec and serve Swagger UI

##### Main Components
A. openapi-yaml-examples
­– Collection of example .yml files illustrating various OpenAPI features
­– No runtime; serves as source artifacts

B. openapi-deployment (Static Swagger UI)
­– index.html + swagger-ui assets
­– openapi.yml (the spec you point Swagger UI at)
­– Deployed to GitHub Pages or any static-file host

C. springboot-openapi-demo (REST Backend)
­– Spring Boot application (monolith)
­– Controllers: CategoryController, OrderController, ProductController
­– Models: Category, Order, Product, Address
­– springdoc-openapi auto-generates openapi.json and serves Swagger UI at /swagger-ui.html
­– application.properties configures server ports and any swagger-springdoc settings

##### Relationships and Data Flow
- Developer edits/specs in openapi-yaml-examples → select one spec for deployment
- Build/deploy openapi-deployment → hosts that spec inside Swagger UI
- Spring Boot app reads annotations on controllers/models → runtime generates OpenAPI JSON → Swagger UI endpoint embedded in app
- External consumer (developer or client) → browses documentation UI (static site or Spring Boot’s UI) → invokes REST endpoints exposed by Spring Boot

##### Key Architectural Patterns & Principles
- Separation of concerns:
- Static spec examples vs. live API demo
- Front-end documentation (Swagger UI) vs. back-end implementation
- Code-First vs. Design-First demonstration:
- Examples folder shows design-first (YAML-first) approach
- Spring Boot demo shows code-first OpenAPI generation
- Monolithic service (single Spring Boot app) with embedded documentation module

##### Essential Elements to Capture
- Flow of API design (YAML) vs. code generation (springdoc)
- Hosting layers (GitHub Pages/static server vs. embedded Swagger UI)
- Client interaction paths for both static docs and live API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    CLIENT["Client / External Consumer"]:::client

    %% SPEC Library
    subgraph "SPEC LIBRARY" 
        SPEC["YAML Spec Collection"]:::artifact
    end

    %% Static Docs Host
    subgraph "STATIC DOCS HOST" 
        SDHOST["Swagger UI Static Deployment"]:::service
        UI["index.html + swagger-ui assets"]:::framework
        YML["openapi.yml"]:::artifact
    end

    %% Spring Boot API
    subgraph "SPRINGBOOT API" 
        SBAPP["Spring Boot Application"]:::service
        subgraph "API Layer (Controllers)"
            CAT_CTRL["CategoryController"]:::controller
            ORD_CTRL["OrderController"]:::controller
            PROD_CTRL["ProductController"]:::controller
        end
        subgraph "Domain Layer (Models)"
            ADDR["Address"]:::model
            CAT_MODEL["Category"]:::model
            ORD_MODEL["Order"]:::model
            PROD_MODEL["Product"]:::model
        end
        SPRINGDOC["springdoc-openapi"]:::framework
        JSON["openapi.json"]:::artifact
        SERVER["Embedded Server (Tomcat)"]:::framework
        CONFIG["application.properties"]:::config
    end

    %% Flows between modules
    SPEC -->|"Select & deploy .yml → Swagger UI"| SDHOST
    SDHOST -->|"Hosts Static Docs"| CLIENT
    CLIENT -->|"Browse UI"| UI
    CLIENT -->|"Browse Live API UI"| SBAPP
    CLIENT -->|"HTTP Requests"| CAT_CTRL
    CAT_CTRL -->|"Invokes Model & Logic"| PROD_MODEL
    CAT_CTRL -->|"Invokes Model & Logic"| ORD_MODEL
    CAT_CTRL -->|"Invokes Model & Logic"| CAT_MODEL
    CAT_CTRL -->|"Invokes Model & Logic"| ADDR
    SUB_CALL1(( ))
    PROD_CTRL -->|"Invokes Model & Logic"| PROD_MODEL
    ORD_CTRL -->|"Invokes Model & Logic"| ORD_MODEL
    PROD_CTRL -->|"Invokes Model & Logic"| ADDR
    ORD_CTRL -->|"Invokes Model & Logic"| ADDR
    PROD_CTRL -->|"Invokes Model & Logic"| CAT_MODEL
    CAT_CTRL -->|"Invokes Model & Logic"| PROD_MODEL

    %% Spec generation
    CAT_CTRL -->|"On startup or on-demand"| SPRINGDOC
    ORD_CTRL --> SPRINGDOC
    PROD_CTRL --> SPRINGDOC
    ADDR --> SPRINGDOC
    CAT_MODEL --> SPRINGDOC
    ORD_MODEL --> SPRINGDOC
    PROD_MODEL --> SPRINGDOC
    SPRINGDOC -->|"Generates"| JSON
    SERVER --> SBAPP
    CONFIG --> SBAPP

    %% Click events
    click SPEC "https://github.com/eazybytes/openapi/tree/main/openapi-yaml-examples/"
    click SDHOST "https://github.com/eazybytes/openapi/tree/main/openapi-deployment/"
    click UI "https://github.com/eazybytes/openapi/blob/main/openapi-deployment/index.html"
    click YML "https://github.com/eazybytes/openapi/blob/main/openapi-deployment/openapi.yml"
    click SBAPP "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/pom.xml"
    click APP "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/OpenApiApplication.java"
    click CAT_CTRL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/controller/CategoryController.java"
    click ORD_CTRL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/controller/OrderController.java"
    click PROD_CTRL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/controller/ProductController.java"
    click ADDR "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/model/Address.java"
    click CAT_MODEL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/model/Category.java"
    click ORD_MODEL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/model/Order.java"
    click PROD_MODEL "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/java/com/eazyshop/OpenAPI/model/Product.java"
    click CONFIG "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/main/resources/application.properties"
    click Tests "https://github.com/eazybytes/openapi/blob/main/springboot-openapi-demo/OpenAPI/src/test/java/com/eazyshop/OpenAPI/OpenApiApplicationTests.java"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef artifact fill:#E6FFED,stroke:#28a745,color:#28a745;
    classDef framework fill:#FFF5E5,stroke:#d9822b,color:#d9822b;
    classDef controller fill:#F0F8FF,stroke:#6C8CD5,color:#6C8CD5;
    classDef model fill:#F5F5F5,stroke:#888888,color:#333333;
    classDef config fill:#FFF0F5,stroke:#CC4477,color:#CC4477;
    classDef client fill:#F0FFF0,stroke:#00A000,color:#00A000;
```
