Skip to content

Commit 22e09ab

Browse files
committed
Initial Code
1 parent dd2fe83 commit 22e09ab

1 file changed

Lines changed: 193 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,199 @@ python -I -m o2j doctor
3939
python -I -m o2j run tests/corpus/02-petstore-3.1/spec.yaml --to plan
4040
```
4141

42+
## Step by step: OpenAPI YAML → Spring Boot REST endpoints
43+
44+
This walkthrough turns your own spec into a running Spring Boot service. Each stage writes its
45+
artifacts under `work/` (override with `--work-dir` or `O2J_WORK_DIR`). The service is written
46+
next to the `o2j.yaml` it was built from. On a failed gate, every command stops with the
47+
exit code listed under [Pipeline](#pipeline).
48+
49+
### 1. Install the prerequisites
50+
51+
| Tool | Needed for |
52+
|---|---|
53+
| Python 3.11+ | the `o2j` CLI |
54+
| JDK 17 / 21 / 25 | building the generated service (must match `target.java_version`) |
55+
| Maven 3.9+ | running `openapi-generator` and the build gates |
56+
| Node.js (`npx`) or `spectral` | house API-standard linting (optional) |
57+
| `gitleaks` | the secret-scanning gate (optional) |
58+
59+
```bash
60+
pip install -e ".[dev,mcp]"
61+
```
62+
63+
### 2. Create a service directory and its config
64+
65+
Keep the service out of the o2j repository: generated sources, scaffolds and `work/` all land
66+
next to `o2j.yaml`.
67+
68+
```bash
69+
mkdir order-service && cd order-service
70+
o2j init --service order-service --base-package com.acme.commerce.order --java 21
71+
```
72+
73+
Then edit `o2j.yaml`:
74+
75+
- `service.group_id`, `service.base_package`: Maven coordinates and Java package.
76+
- `target.java_version` and `target.spring_profile` (`spring-boot-3` or `spring-boot-4`).
77+
- `openapi.input`: path to your spec (default `openapi/spec.raw.yaml`).
78+
- `quality.mutation.target_packages`: set this to your `<base_package>.service.*`.
79+
- `ems`: only if you are replacing TIBCO EMS queues (see [below](#replacing-tibco-ems-queues)).
80+
81+
### 3. Check the toolchain
82+
83+
```bash
84+
python -I -m o2j doctor
85+
```
86+
87+
Any `MISS` line prints a remedy. Fix those before going on. Add `--check-versions` to see
88+
whether the pinned versions in `o2j.yaml` are behind Maven Central.
89+
90+
### 4. Ingest the spec (S0)
91+
92+
```bash
93+
python -I -m o2j ingest openapi/spec.raw.yaml
94+
```
95+
96+
Copies the spec into quarantine (`work/00-ingest/`), checks its size and extension, records
97+
its hash and detects the version (Swagger 2.0, OpenAPI 3.0, 3.1 or 3.2).
98+
99+
### 5. Validate it (S1)
100+
101+
```bash
102+
python -I -m o2j validate openapi/spec.raw.yaml
103+
```
104+
105+
Checks syntax, semantics and the house rules: security on every operation, pagination on
106+
collections, Problem Details error responses, naming. Each finding prints a `fix:` hint, and a
107+
SARIF report is written to `work/01-validate/` for code-scanning UIs. **Fix the spec, not the
108+
generated code.** Exit `3` means at least one error remains.
109+
110+
### 6. Normalize to the canonical version (S2)
111+
112+
```bash
113+
python -I -m o2j normalize openapi/spec.raw.yaml
114+
```
115+
116+
Converts the spec to OpenAPI 3.1.2, the version the Java toolchain accepts. Swagger 2.0 and 3.0
117+
are upgraded. 3.2 is downgraded, and anything with no 3.1 equivalent fails with exit `4`.
118+
Text aimed at agents is redacted and each removal is recorded. The output is the canonical
119+
spec path and its hash, which every later stage builds from.
120+
121+
### 7. Plan the endpoints and required tests (S3)
122+
123+
```bash
124+
python -I -m o2j plan
125+
python -I -m o2j testplan
126+
```
127+
128+
`plan` lists every operation and resource, a risk score with its drivers, and the test cases
129+
each operation's shape requires. `testplan` prints those cases as the `// o2j:<operationId>:<case>`
130+
markers the tests must carry. Review a `high` risk band before building logic on the model.
131+
132+
### 8. Generate the Spring Boot code (S4)
133+
134+
```bash
135+
python -I -m o2j generate
136+
```
137+
138+
Runs `openapi-generator` through Maven and scaffolds the rest. Layout, under
139+
`src/main/java/<base_package>/`:
140+
141+
| Package | Contents | Who owns it |
142+
|---|---|---|
143+
| `target/generated-sources/openapi` | DTOs, `*Api` interfaces, `*ApiController` | generator: never edit |
144+
| `api/` | `*ApiDelegateImpl`: one method per endpoint | you |
145+
| `service/` | business services the delegates call | you |
146+
| `mapper/` | MapStruct mappers between DTOs and domain types | you |
147+
| `config/` | `SecurityConfig`, `OpenApiSecurityRules`, correlation-id filter | o2j |
148+
| `error/` | `GlobalExceptionHandler` (RFC 9457 Problem Details), domain exceptions | o2j |
149+
150+
Contract tests in `src/test/java` are regenerated on every run, and `@Disabled` skeletons are
151+
created for the business cases. If a scaffolded file you changed would be overwritten,
152+
o2j writes `<file>.o2j-new` and reports a `CONFLICT` for you to merge by hand. Use
153+
`--no-run-generator` to scaffold without Maven.
154+
155+
Confirm that regenerating gives byte-identical output:
156+
157+
```bash
158+
python -I -m o2j verify --mode determinism
159+
```
160+
161+
### 9. Implement the endpoints
162+
163+
The generated controller handles routing, binding and validation, then calls your delegate. For
164+
each operation:
165+
166+
1. Implement the method in `api/<Resource>ApiDelegateImpl`: map the request DTO with the
167+
mapper, call the service, map the result back and return a `ResponseEntity` with the status
168+
the spec declares.
169+
2. Put the business rules in `service/<Resource>Service`. Throw `NotFoundException` or
170+
`ConflictException` and the handler turns them into 404 and 409 Problem Details.
171+
3. Keep generated DTOs inside `api` and `mapper`. `ArchitectureTest` fails the build if they
172+
leak further.
173+
174+
In VS Code with Copilot, the `service-implementer` agent does this step. The
175+
`/convert-openapi` prompt runs the whole pipeline through the `openapi-to-spring` orchestrator.
176+
177+
### 10. Write the business tests
178+
179+
Fill in the `@Disabled` methods in `<Service>Test` (Mockito) and `<Api>BehaviourTest` (web
180+
slice), then remove `@Disabled`. Keep each method's `// o2j:` marker. The `test-author` agent
181+
can do this.
182+
183+
```bash
184+
python -I -m o2j verify --mode contract --static # markers are on test methods
185+
```
186+
187+
### 11. Build and run the gates (S7)
188+
189+
```bash
190+
mvn verify
191+
python -I -m o2j quality # Spotless, Checkstyle, PMD, SpotBugs, ArchUnit, OWASP, gitleaks
192+
python -I -m o2j coverage --no-run-build # line, branch, service-layer and mutation thresholds
193+
python -I -m o2j verify --mode contract # every required case claimed by a passing test
194+
python -I -m o2j verify --mode conformance # every recorded response matches the spec
195+
```
196+
197+
The default thresholds are 85% line, 80% branch, 90% service-layer line and 70% mutation score,
198+
all set in `o2j.yaml`. Exit `6` means a gate failed.
199+
200+
### 12. Report and run the service (S8)
201+
202+
```bash
203+
python -I -m o2j report
204+
JWT_ISSUER_URI=https://your-idp/realms/main mvn spring-boot:run
205+
```
206+
207+
`report` writes the manifest, the traceability matrix (operation → code → tests) and a PR body
208+
to `work/08-report/`. The service starts on port 8080. springdoc serves the live contract at
209+
`/v3/api-docs` and Swagger UI at `/swagger-ui.html`. Secured endpoints need a JWT from the
210+
issuer in `JWT_ISSUER_URI`. Without that variable the service rejects every token, so it fails
211+
closed.
212+
213+
### All at once
214+
215+
Once the steps are familiar, one command runs any range of stages and stops at the first
216+
failed gate:
217+
218+
```bash
219+
python -I -m o2j run openapi/spec.raw.yaml # ingest -> report
220+
python -I -m o2j run openapi/spec.raw.yaml --to generate # stop after codegen
221+
python -I -m o2j run --from gate --to report # re-gate after implementing
222+
python -I -m o2j run openapi/spec.raw.yaml --java 17 # override the Java target
223+
```
224+
225+
Stages: `ingest`, `validate`, `normalize`, `plan`, `generate`, `gate`, `report`.
226+
227+
### When the spec changes
228+
229+
Edit the spec and re-run from `ingest`. Generated code and contract tests are rebuilt.
230+
Scaffolds you already edited are kept, and any that conflict show up as `.o2j-new`. Use
231+
`python -I -m o2j verify --mode drift` to check whether the code still matches the spec, and
232+
set `validation.breaking_change_baseline` to the previous spec so breaking changes are flagged
233+
during validation.
234+
42235
## Pipeline
43236

44237
| Stage | Command | Gate |

0 commit comments

Comments
 (0)