@@ -39,6 +39,199 @@ python -I -m o2j doctor
3939python -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