Migrate project artifacts to spec-kit format
- Move cross-cutting docs (personas, design system, implementation phases, Ideen.md) to .specify/memory/ - Move cross-cutting research and plans to .specify/memory/research/ and .specify/memory/plans/ - Extract 5 setup tasks from spec/setup-tasks.md into individual specs/001-005/spec.md files with spec-kit template format - Extract 20 user stories from spec/userstories.md into individual specs/006-026/spec.md files with spec-kit template format - Relocate feature-specific research and plan docs into specs/[feature]/ - Add spec-kit constitution, templates, scripts, and slash commands - Slim down CLAUDE.md to Claude-Code-specific config, delegate principles to .specify/memory/constitution.md - Update ralph.sh with stream-json output and per-iteration logging - Delete old spec/ and docs/agents/ directories - Gitignore Ralph iteration JSONL logs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
100
specs/005-api-first-tooling/spec.md
Normal file
100
specs/005-api-first-tooling/spec.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Feature Specification: API-First Tooling Setup
|
||||
|
||||
**Feature**: `005-api-first-tooling`
|
||||
**Created**: 2026-03-06
|
||||
**Status**: Implemented
|
||||
**Source**: Migrated from spec/setup-tasks.md (setup task — infrastructure, not user-facing)
|
||||
|
||||
## User Scenarios & Testing
|
||||
|
||||
### Setup Story 1 - Backend OpenAPI Code Generation (Priority: P1)
|
||||
|
||||
The development toolchain generates Java server interfaces and model classes from the OpenAPI spec so that the backend implementation always matches the API contract.
|
||||
|
||||
**Why this priority**: Code generation from the spec is the foundation of API-first development. Without it, backend implementation can diverge from the contract.
|
||||
|
||||
**Independent Test**: Run `./mvnw compile` and verify that generated sources appear in `target/generated-sources/openapi/`.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the OpenAPI spec exists at `backend/src/main/resources/openapi/api.yaml`, **When** `./mvnw compile` is run, **Then** Java interfaces and model classes are generated into `target/generated-sources/openapi/` with packages `de.fete.adapter.in.web.api` and `de.fete.adapter.in.web.model`.
|
||||
2. **Given** the generator is configured with `interfaceOnly: true`, **When** compilation completes, **Then** only interfaces (not implementations) are generated, keeping implementation separate from contract.
|
||||
|
||||
---
|
||||
|
||||
### Setup Story 2 - Frontend TypeScript Type Generation (Priority: P1)
|
||||
|
||||
The development toolchain generates TypeScript types from the OpenAPI spec so that the frontend is always type-safe against the API contract.
|
||||
|
||||
**Why this priority**: Type generation ensures frontend-backend contract alignment at compile time.
|
||||
|
||||
**Independent Test**: Run `npm run generate:api` and verify that `frontend/src/api/schema.d.ts` is created with types matching the spec.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** `openapi-typescript` is installed as a devDependency and `openapi-fetch` as a dependency, **When** `npm run generate:api` is run, **Then** TypeScript types are generated into `frontend/src/api/schema.d.ts`.
|
||||
2. **Given** the `dev` and `build` scripts include type generation as a pre-step, **When** `npm run dev` or `npm run build` is run, **Then** types are regenerated automatically before the build proceeds.
|
||||
|
||||
---
|
||||
|
||||
### Setup Story 3 - Minimal API Client (Priority: P2)
|
||||
|
||||
A minimal API client using `openapi-fetch` is wired up so that frontend code can call the backend with full type safety.
|
||||
|
||||
**Why this priority**: The client is needed before any user story can make API calls, but can be a thin wrapper initially.
|
||||
|
||||
**Independent Test**: Verify `frontend/src/api/client.ts` exists and uses `createClient<paths>()` from `openapi-fetch`.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the generated `schema.d.ts` exists, **When** a developer imports the API client, **Then** all request/response types are fully inferred from the OpenAPI spec.
|
||||
|
||||
---
|
||||
|
||||
### Setup Story 4 - Minimal OpenAPI Spec (Priority: P1)
|
||||
|
||||
A minimal OpenAPI 3.1 spec exists at the canonical location and is sufficient to prove the tooling works end-to-end.
|
||||
|
||||
**Why this priority**: The spec is the prerequisite for all code generation. It must exist before any other story can proceed.
|
||||
|
||||
**Independent Test**: Run both generation steps (backend + frontend) and verify both succeed without errors.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a minimal spec at `backend/src/main/resources/openapi/api.yaml`, **When** both generation steps run, **Then** both complete successfully and the project compiles cleanly (backend + frontend).
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when the OpenAPI spec contains a syntax error? Generation should fail with a clear error message.
|
||||
- What happens when the spec is updated with a breaking change? Generated types and interfaces reflect the change, causing compile errors that force the developer to update implementations.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: `openapi-generator-maven-plugin` (v7.20.x, `spring` generator, `interfaceOnly: true`) MUST be configured in `backend/pom.xml`.
|
||||
- **FR-002**: A minimal OpenAPI 3.1 spec MUST exist at `backend/src/main/resources/openapi/api.yaml`.
|
||||
- **FR-003**: `./mvnw compile` MUST generate 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`.
|
||||
- **FR-004**: `openapi-typescript` MUST be installed as a devDependency in the frontend.
|
||||
- **FR-005**: `openapi-fetch` MUST be installed as a runtime dependency in the frontend.
|
||||
- **FR-006**: `npm run generate:api` MUST generate TypeScript types from the spec into `frontend/src/api/schema.d.ts`.
|
||||
- **FR-007**: Frontend `dev` and `build` scripts MUST include type generation as a pre-step.
|
||||
- **FR-008**: A minimal API client at `frontend/src/api/client.ts` MUST use `createClient<paths>()` from `openapi-fetch`.
|
||||
- **FR-009**: Both generation steps MUST succeed and the project MUST compile cleanly (backend + frontend).
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **OpenAPI Spec**: The single source of truth for the REST API contract, located at `backend/src/main/resources/openapi/api.yaml`. A living document that grows with each user story.
|
||||
- **Generated Sources**: Backend Java interfaces/models in `target/generated-sources/openapi/`; frontend TypeScript types in `frontend/src/api/schema.d.ts`.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: `./mvnw compile` succeeds and generated sources exist in `target/generated-sources/openapi/`.
|
||||
- **SC-002**: `npm run generate:api` succeeds and `frontend/src/api/schema.d.ts` is created.
|
||||
- **SC-003**: Frontend `npm run dev` and `npm run build` automatically regenerate types before building.
|
||||
- **SC-004**: The project compiles cleanly end-to-end (backend + frontend) with the generated code.
|
||||
- **SC-005**: A working API client exists at `frontend/src/api/client.ts` using the generated types.
|
||||
Reference in New Issue
Block a user