feat: migrate to OpenAPI 3.0 with oneOf unions

- Add swagger2openapi conversion step to generate OpenAPI 3.0
- Add patch-openapi.ts script to inject oneOf discriminated unions
- Update docs server to embed static openapi.json
- Update moveItemsToDirectory response to use oneOf for items
- Add docs/README.md documenting the pipeline
- Use bun instead of node for scripts

apps/backend/Makefile

@@ -21,9 +21,13 @@ run-docs:
 
 # Generate API documentation
 docs:
-	@echo "Generating OpenAPI documentation..."
-	swag init -g cmd/drexa/main.go -o docs --parseDependency --parseInternal --outputTypes go,json,yaml
-	@echo "Documentation generated in docs/"
+	@echo "Generating Swagger 2.0 documentation..."
+	swag init -g cmd/drexa/main.go -o docs --parseDependency --parseInternal --outputTypes json
+	@echo "Converting to OpenAPI 3.0..."
+	bunx --bun swagger2openapi docs/swagger.json -o cmd/docs/openapi.json --patch
+	@echo "Patching OpenAPI spec with oneOf types..."
+	bun scripts/patch-openapi.ts cmd/docs/openapi.json
+	@echo "Documentation generated in docs/ and cmd/docs/"
 	@echo "Run 'make run-docs' to start the documentation server"
 
 # Install development tools
@@ -38,4 +42,4 @@ fmt:
 # Clean build artifacts
 clean:
 	rm -rf bin/
-	rm -f docs/swagger.json docs/swagger.yaml
+	rm -f docs/swagger.json docs/swagger.yaml cmd/docs/openapi.json