nitrix/fete
1
0
Fork 0
Code Issues 1 Pull Requests 10 Actions Packages Projects Releases 13 Wiki Activity

T-5: set up API-first tooling with OpenAPI spec as single source of truth

Browse Source 
Backend: openapi-generator-maven-plugin generates Spring interfaces and DTOs
from the spec. Frontend: openapi-typescript + openapi-fetch provide type-safe
API access. Both sides get compile-time contract enforcement from a single
api.yaml file.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nitrix
2026-03-04 18:04:55 +01:00
parent 1ed379bc1c
commit 5ad6a08b72
9 changed files with 388 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
spec/setup-tasks.md
View File

@@ -60,14 +60,14 @@
**Description:** Set up the API-first development workflow. The OpenAPI spec is the single source of truth for the REST API contract. Backend server interfaces and frontend TypeScript types are generated from it. This task scaffolds the tooling and creates a minimal initial spec — the spec itself is a living document that grows with each user story.
**Acceptance Criteria:**
- [ ] `openapi-generator-maven-plugin` (v7.20.x, `spring` generator, `interfaceOnly: true`) is configured in `backend/pom.xml`
- [ ] A minimal OpenAPI 3.1 spec exists at `backend/src/main/resources/openapi/api.yaml` (info block, placeholder path, or health-only — enough for the generator to run)
- [ ] `mvnw compile` generates Java interfaces and model classes into `target/generated-sources/openapi/` with packages `de.fete.adapter.in.web.api` and `de.fete.adapter.in.web.model`
- [ ] `openapi-typescript` (devDependency) and `openapi-fetch` (dependency) are installed in the frontend
- [ ] `npm run generate:api` generates TypeScript types from the spec into `frontend/src/api/schema.d.ts`
- [ ] Frontend `dev` and `build` scripts include type generation as a pre-step
- [ ] A minimal API client (`frontend/src/api/client.ts`) using `openapi-fetch` with `createClient<paths>()` exists
- [ ] Both generation steps succeed and the project compiles cleanly (backend + frontend)
- [x] `openapi-generator-maven-plugin` (v7.20.x, `spring` generator, `interfaceOnly: true`) is configured in `backend/pom.xml`
- [x] A minimal OpenAPI 3.1 spec exists at `backend/src/main/resources/openapi/api.yaml` (info block, placeholder path, or health-only — enough for the generator to run)
- [x] `mvnw compile` generates Java interfaces and model classes into `target/generated-sources/openapi/` with packages `de.fete.adapter.in.web.api` and `de.fete.adapter.in.web.model`
- [x] `openapi-typescript` (devDependency) and `openapi-fetch` (dependency) are installed in the frontend
- [x] `npm run generate:api` generates TypeScript types from the spec into `frontend/src/api/schema.d.ts`
- [x] Frontend `dev` and `build` scripts include type generation as a pre-step
- [x] A minimal API client (`frontend/src/api/client.ts`) using `openapi-fetch` with `createClient<paths>()` exists
- [x] Both generation steps succeed and the project compiles cleanly (backend + frontend)
**Dependencies:** T-1