feat: add OpenAPI spec (dev only) with typed frontend client

- Add springdoc-openapi 3.0.2 (supports Spring Boot 4) to backend
- Disable api-docs/swagger-ui in application.yaml (prod default)
- Enable both in application-dev.yaml; Swagger UI at /swagger-ui.html
- Add openapi-fetch (runtime) and openapi-typescript (dev) to frontend
- Add generate:api npm script — run with backend up to regenerate types
- Add src/lib/api.server.ts typed client factory (uses SvelteKit fetch)
- Gitignore src/lib/generated/api.ts (generated artifact)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/pom.xml

@@ -136,6 +136,13 @@
 			<groupId>org.flywaydb</groupId>
 			<artifactId>flyway-database-postgresql</artifactId>
 		</dependency>
+
+		<!-- OpenAPI / Swagger UI — enabled only in the dev Spring profile -->
+		<dependency>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+			<version>3.0.2</version>
+		</dependency>
 	</dependencies>
 
 

backend/src/main/resources/application-dev.yaml

@@ -1,3 +1,10 @@
 spring:
   jpa:
     show-sql: true
+
+springdoc:
+  api-docs:
+    enabled: true
+  swagger-ui:
+    enabled: true
+    path: /swagger-ui.html

backend/src/main/resources/application.yaml

@@ -21,6 +21,12 @@ spring:
       max-file-size: 50MB
       max-request-size: 50MB
 
+springdoc:
+  api-docs:
+    enabled: false
+  swagger-ui:
+    enabled: false
+
 app:
   s3:
     endpoint: ${S3_ENDPOINT}

frontend/.gitignore

@@ -24,3 +24,6 @@ vite.config.ts.timestamp-*
 
 # Paraglide
 src/lib/paraglide
+
+# Generated OpenAPI types — regenerate with: npm run generate:api
+src/lib/generated/api.ts

frontend/package.json

@@ -13,9 +13,14 @@
 		"format": "prettier --write .",
 		"lint": "prettier --check . && eslint .",
 		"test:unit": "vitest",
-		"test": "npm run test:unit -- --run"
+		"test": "npm run test:unit -- --run",
+		"generate:api": "openapi-typescript http://localhost:8080/v3/api-docs -o ./src/lib/generated/api.ts"
+	},
+	"dependencies": {
+		"openapi-fetch": "^0.13.5"
 	},
 	"devDependencies": {
+		"openapi-typescript": "^7.8.0",
 		"@eslint/compat": "^1.4.0",
 		"@eslint/js": "^9.39.1",
 		"@inlang/paraglide-js": "^2.5.0",

frontend/src/lib/api.server.ts

@@ -0,0 +1,25 @@
+/**
+ * Typed API client for the Familienarchiv backend.
+ *
+ * Types are generated from the OpenAPI spec — run `npm run generate:api`
+ * (with the backend running in dev mode) to regenerate src/lib/generated/api.ts.
+ *
+ * Usage in +page.server.ts:
+ *
+ *   export async function load({ fetch }) {
+ *       const api = createApiClient(fetch);
+ *       const { data, error } = await api.GET('/api/documents/{id}', {
+ *           params: { path: { id } }
+ *       });
+ *   }
+ */
+import createClient from 'openapi-fetch';
+import { env } from '$env/dynamic/private';
+import type { paths } from '$lib/generated/api';
+
+export function createApiClient(fetch: typeof globalThis.fetch) {
+    return createClient<paths>({
+        baseUrl: env.API_INTERNAL_URL || 'http://localhost:8080',
+        fetch
+    });
+}