How eazybytes/openapi works
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