Skip to content

Commit 5ddba88

Browse files
rexrkrexrk
committed
Readme updates
1 parent 344fd17 commit 5ddba88

5 files changed

Lines changed: 309 additions & 147 deletions

File tree

‎README.md‎

Lines changed: 75 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,95 @@
1-
# 🚀 AI Dev Tools for Spring Boot
1+
# AI Dev Tools for Spring Boot
22

3-
A collection of **AI-powered Spring Boot starters** focused on **enhancing developer experience (DX)** during local development and testing.
3+
`ai-dev-tools` is a multi-module Maven workspace for Spring Boot developer tooling. The modules in this repository focus on local development workflows such as Swagger payload generation, exception capture, and live debugging dashboards.
44

5-
This repository contains production-grade tooling ideas that integrate deeply with the Spring ecosystem to help developers:
6-
- Fix APIs faster
7-
- Reduce repetitive work
8-
- Improve development experience during local runs
5+
## Modules
96

10-
> 🎯 **Goal**: Build AI-assisted developer tooling, not end-user applications.
7+
| Module | Purpose |
8+
| --- | --- |
9+
| `ai-swagger-helper-starter` | Injects a Swagger UI plugin that can generate JSON request bodies from OpenAPI schemas. |
10+
| `ai-exception-insights-starter` | Captures runtime failures, stores recent error events, and asks a Spring AI chat model for a short diagnosis. |
11+
| `dev-tools-ui` | Reusable SSE dashboard module used by the exception starter for browser-based output. |
12+
| `demo-app` | Sample application that wires the starters together and exposes endpoints to try them. |
1113

12-
---
14+
Each module has its own README with module-specific setup and usage details.
1315

14-
## 📦 Repository Structure
16+
## Stack
1517

16-
This is a **multi-module Maven project** with a shared parent POM.
17-
```
18-
ai-dev-tools
19-
├── .github/workflows
20-
├── LICENCE
21-
├── pom.xml # Parent POM
22-
├── ai-swagger-helper-starter # Swagger/OpenAPI DX tools
23-
├── demo-app # Usage example for all starters
24-
└── README.md
25-
```
26-
27-
28-
Each module:
29-
- Is a **Spring Boot starter**
30-
- Is independently usable
31-
- Focuses on a specific developer pain point
32-
33-
---
34-
35-
## 🧠 Why AI + Spring Boot Starters?
36-
37-
Traditional developer tools provide **raw data** (logs, specs, stack traces).
38-
These starters use AI to convert that data into **actionable insights**.
39-
40-
Examples:
41-
- Explaining *why* an API change is breaking
42-
- Generating realistic request payloads from OpenAPI
43-
- Summarizing errors instead of dumping stack traces
44-
- Reducing cognitive load during development
45-
46-
AI is used **only where reasoning or summarization adds value**, not as a gimmick.
18+
- Java 21
19+
- Spring Boot 4.0.2
20+
- Spring AI 2.0.0-M2
21+
- Maven multi-module build
22+
- `springdoc-openapi` for Swagger UI integration
4723

48-
---
24+
## Prerequisites
4925

50-
## 🧩 Available Starters
26+
- JDK 21
27+
- Maven 3.9+ or the included wrapper
28+
- An OpenAI-compatible API key if you want live AI responses
5129

52-
### 1️⃣ AI Swagger Helper Starter
53-
📁 `ai-swagger-helper-starter`
30+
The repository already includes sample configuration for an OpenAI-compatible endpoint through Spring AI. The demo app uses OpenRouter through the OpenAI adapter.
5431

55-
Enhancements for Swagger / OpenAPI during development.
32+
## Build
5633

57-
**Features**
58-
- Adds a Swagger UI extension
59-
- Generates realistic, real-world request bodies
60-
- Helps developers test APIs faster without manually crafting payloads
34+
Unix-like shells:
6135

62-
**Use case**
63-
- Local development
64-
- API testing
65-
66-
---
67-
68-
## 🛠 Planned / In-Progress Starters
69-
70-
- **AI Exception Explainer Starter**
71-
Converts Spring stack traces into human-readable explanations.
72-
73-
- **AI Exception Handler**
36+
```bash
37+
./mvnw test
38+
```
7439

75-
(Each starter will live in its own module with independent documentation.)*
40+
Windows PowerShell:
7641

77-
---
42+
```powershell
43+
.\mvnw.cmd test
44+
```
7845

46+
## Run the Demo App
7947

80-
## 🧰 Tech Stack
48+
Set an API key first if you want AI-backed generation and exception analysis:
8149

82-
- Java 21+
83-
- Spring Boot 4
84-
- Spring Auto-Configuration
85-
- OpenAPI / Swagger
86-
- Maven (multi-module)
87-
- OpenRouter LLM integration (pluggable)
50+
```powershell
51+
$env:API_KEY="your-api-key"
52+
.\mvnw.cmd -pl demo-app -am spring-boot:run
53+
```
8854

89-
---
55+
Useful URLs after startup:
56+
57+
- Dashboard: `http://localhost:8081/`
58+
- Swagger UI: `http://localhost:8081/swagger-ui/index.html`
59+
- Exception event API: `http://localhost:8081/exception-insights/events`
60+
61+
Demo endpoints:
62+
63+
- `POST /test/generate` for Swagger request-body generation
64+
- `GET /boom/http` for HTTP exception capture
65+
- `GET /boom/async` for `@Async` exception capture
66+
- `GET /boom/thread` for uncaught thread exception capture
67+
- `GET /boom/event` for an event-listener failure triggered from an HTTP request
68+
69+
## Configuration Example
70+
71+
```yaml
72+
spring:
73+
ai:
74+
openai:
75+
api-key: ${API_KEY}
76+
chat:
77+
base-url: https://openrouter.ai/api
78+
options:
79+
model: inclusionai/ling-2.6-1t:free
80+
81+
devtools:
82+
ai:
83+
swagger-helper:
84+
enabled: true
85+
mode: ai
86+
exception-insights:
87+
enabled: true
88+
output: ui
89+
```
9090
91-
## 📌 Who Is This For?
91+
## Notes
9292
93-
- Backend developers working with Spring Boot
94-
- Engineers interested in platform / tooling work
95-
- Developers exploring AI-assisted development workflows
93+
- `ai-swagger-helper-starter` supports `AUTO`, `AI`, and `RANDOM` modes.
94+
- `ai-exception-insights-starter` stores events in memory only and can output to the console or the browser UI.
95+
- `dev-tools-ui` is reusable, but the shipped dashboard is currently tailored to the exception starter's REST and SSE contract.

‎ai-exception-insights-starter/README.md‎

Lines changed: 78 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,84 @@
1-
# Getting Started
1+
# ai-exception-insights-starter
22

3-
### Reference Documentation
3+
`ai-exception-insights-starter` captures runtime failures, stores recent error events in memory, and asks a Spring AI chat model for a short explanation with suggested fixes.
44

5-
For further reference, please consider the following sections:
5+
## What It Captures
66

7-
* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
8-
* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/4.0.3/maven-plugin)
9-
* [Create an OCI image](https://docs.spring.io/spring-boot/4.0.3/maven-plugin/build-image.html)
7+
- Unhandled HTTP exceptions in web applications
8+
- `@Async` uncaught exceptions
9+
- Scheduled-task exceptions when the host app enables scheduling
10+
- Uncaught thread exceptions
11+
- Recent `WARN` and `ERROR` log lines from a small in-memory ring buffer
1012

11-
### Maven Parent overrides
13+
Each captured event includes exception details, a short fingerprint for deduplication, recent logs, and an asynchronously populated AI explanation.
1214

13-
Due to Maven's design, elements are inherited from the parent POM to the project POM.
14-
While most of the inheritance is fine, it also inherits unwanted elements like `<license>` and `<developers>` from the
15-
parent.
16-
To prevent this, the project POM contains empty overrides for these elements.
17-
If you manually switch to a different parent and actually want the inheritance, you need to remove those overrides.
15+
## Dependency
1816

17+
```xml
18+
<dependency>
19+
<groupId>io.github.rexrk</groupId>
20+
<artifactId>ai-exception-insights-starter</artifactId>
21+
<version>0.0.1-SNAPSHOT</version>
22+
</dependency>
23+
```
24+
25+
## Configuration
26+
27+
| Property | Default | Description |
28+
| --- | --- | --- |
29+
| `devtools.ai.exception-insights.enabled` | `true` | Enables the starter auto-configuration. |
30+
| `devtools.ai.exception-insights.max-events` | `10` | Maximum number of events retained in memory. |
31+
| `devtools.ai.exception-insights.deduplication-window` | `5s` | Drops duplicate fingerprints seen inside this window. |
32+
| `devtools.ai.exception-insights.log-buffer-size` | `5` | Number of recent `WARN`/`ERROR` log lines retained. |
33+
| `devtools.ai.exception-insights.output` | `CONSOLE` | Output mode: `CONSOLE` or `UI`. |
34+
35+
Example:
36+
37+
```yaml
38+
devtools:
39+
ai:
40+
exception-insights:
41+
enabled: true
42+
max-events: 25
43+
deduplication-window: 10s
44+
log-buffer-size: 20
45+
output: ui
46+
```
47+
48+
Spring AI example:
49+
50+
```yaml
51+
spring:
52+
ai:
53+
openai:
54+
api-key: ${API_KEY}
55+
```
56+
57+
## Runtime Endpoints
58+
59+
The starter exposes a small inspection API:
60+
61+
- `GET /exception-insights/events?limit=20`
62+
- `GET /exception-insights/events/{id}`
63+
- `DELETE /exception-insights/events`
64+
65+
## Output Modes
66+
67+
### `CONSOLE`
68+
69+
Logs a formatted error block when an event is captured and logs a second block when the AI explanation is ready.
70+
71+
### `UI`
72+
73+
Uses the bundled `dev-tools-ui` dependency to broadcast SSE events and render the dashboard in the browser. In this mode:
74+
75+
- the dashboard is available from the app's root static page
76+
- SSE is exposed from `/dev-tools/stream`
77+
- the exception API continues to serve full event details
78+
79+
## Behavior Notes
80+
81+
- Storage is in-memory only; restarting the app clears history.
82+
- HTTP request capture excludes `Authorization` and `Cookie` headers from the stored request-header map.
83+
- Scheduled-task capture only activates in applications that already enable scheduling.
84+
- If the AI call fails, the event is still stored and the explanation is replaced with a fallback message.

‎ai-swagger-helper-starter/README.md‎

Lines changed: 54 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,26 @@
1-
# DevTools AI – Swagger Helper Starter
1+
# ai-swagger-helper-starter
22

3-
A Spring Boot starter that improves **Swagger / OpenAPI developer experience** by automatically generating request bodies during development.
3+
`ai-swagger-helper-starter` adds a small Swagger UI extension plus a backend generator endpoint so developers can fill JSON request bodies without hand-writing payloads during local API testing.
44

5-
The starter supports both **local random generation** and **optional AI-powered generation** (via Spring AI), with safe fallbacks and zero impact on application startup.
5+
## What the Starter Adds
66

7-
AI is treated as an **optional enhancement**, not a requirement.
7+
- A Swagger UI plugin injected into springdoc's `index.html`
8+
- A "generate body" action inside the request-body editor
9+
- `POST /devtools/ai/request-body/generate`
10+
- Three generation modes:
11+
- `RANDOM`: local schema-driven sample generation
12+
- `AI`: Spring AI chat-model generation
13+
- `AUTO`: AI when available, otherwise local generation
814

9-
---
15+
When AI generation fails or returns invalid JSON, the starter falls back to the local generator.
1016

11-
## 🎯 Problem
17+
## Requirements
1218

13-
During backend development, generating request bodies for APIs is:
19+
- Spring MVC application
20+
- `springdoc-openapi-starter-webmvc-ui` on the host application classpath
21+
- Spring AI model configuration if you want `AI` or `AUTO` mode to use a real chat model
1422

15-
- repetitive
16-
- time-consuming
17-
- error-prone
18-
- especially painful for complex schemas
19-
20-
Swagger UI shows schemas, but developers still have to manually craft payloads.
21-
22-
This starter removes that friction.
23-
24-
---
25-
26-
## ✨ Features
27-
28-
- Swagger UI extension with **Generate Request Body** action
29-
- Local random request body generation (default)
30-
- Optional AI-powered request body generation
31-
- Automatic fallback to random generation on AI failure
32-
- Fully configurable via properties
33-
34-
---
35-
36-
## 📦 Installation
37-
38-
### Maven
23+
## Dependency
3924

4025
```xml
4126
<dependency>
@@ -45,33 +30,54 @@ This starter removes that friction.
4530
</dependency>
4631
```
4732

48-
---
33+
## Configuration
34+
35+
| Property | Default | Description |
36+
| --- | --- | --- |
37+
| `devtools.ai.swagger-helper.enabled` | `true` | Enables the starter auto-configuration. |
38+
| `devtools.ai.swagger-helper.mode` | `AUTO` | Generation mode: `AUTO`, `AI`, or `RANDOM`. |
4939

50-
## ⚙️ Configuration
40+
Example:
5141

52-
Configure Spring AI (example with OpenAI):
5342
```yaml
54-
spring:
43+
devtools:
5544
ai:
56-
openai:
57-
api-key: YOUR_API_KEY
45+
swagger-helper:
46+
enabled: true
47+
mode: auto
5848
```
5949
50+
Spring AI example with the OpenAI adapter:
6051
6152
```yaml
62-
devtools:
53+
spring:
6354
ai:
64-
swagger:
65-
enabled: true
66-
mode: random
55+
openai:
56+
api-key: ${API_KEY}
6757
```
6858
69-
## 🔁 Generation Modes
59+
## How It Works
60+
61+
1. The frontend plugin resolves `$ref` entries from the loaded OpenAPI document.
62+
2. It posts a resolved schema to `/devtools/ai/request-body/generate`.
63+
3. The backend returns a JSON string.
64+
4. Swagger UI writes that JSON back into the request-body editor.
65+
66+
The local generator supports:
67+
68+
- objects and nested objects
69+
- arrays
70+
- enums
71+
- primitive types
72+
- string formats such as `date`, `date-time`, `email`, `uuid`, and `uri`
73+
74+
## Usage
75+
76+
1. Start an application that includes this starter and springdoc Swagger UI.
77+
2. Open Swagger UI.
78+
3. Expand an operation that accepts a JSON request body.
79+
4. Use the generated-body action in the request editor.
7080

71-
| Mode | Behavior |
72-
|-----|----------|
73-
| random | Always use local random generation |
74-
| ai | Use AI if available, fallback to random |
75-
| auto | Use AI when configured, otherwise random |
81+
## Current Limitation
7682

77-
---
83+
The current frontend plugin scans the loaded OpenAPI document and uses the first JSON request-body schema it finds. In specs with multiple request-body operations, generation may not always map to the currently selected operation.

0 commit comments

Comments
 (0)