Skip to content

Refactor project structure and implement standardized API generation #891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

Refactor project structure and implement standardized API generation #891

wants to merge 10 commits into from

Conversation

@pditommaso
Copy link
Collaborator

Summary

This PR implements a comprehensive refactoring of the Wave project structure and establishes a standardized API generation workflow aligned with app-bootstrap patterns.

🏗️ Project Structure Refactoring

  • Split monolithic project into wave-api and wave-app modules
  • Moved API definitions to dedicated wave-api module
  • Separated application code to wave-app module
  • Preserved current API classes while introducing new package structure

📦 Package Strategy

  • Current API classes: io.seqera.wave.api (preserved)
  • Generated models: io.seqera.wave.api.schema.v0 (new versioned package)
  • Generated specs: io.seqera.wave.api.spec (following app-bootstrap pattern)

🔧 OpenAPI & Documentation Generation

  • TypeSpec integration for API definition and OpenAPI spec generation
  • Micronaut OpenAPI plugin for server-side code generation
  • Swagger UI integration with WebJars for interactive documentation
  • Versioned API documentation with automatic version management

✅ OpenAPI Endpoint Fix

  • Resolved /openapi redirect loop by removing controller interference
  • Leveraged Micronaut static resource serving for proper documentation hosting
  • Aligned with app-bootstrap patterns for consistent behavior

🎯 Build Configuration Standardization

  • Identical task structure with app-bootstrap project
  • Consistent dependency patterns across modules
  • Standardized OpenAPI configuration with proper code generation settings
  • Unified Swagger UI generation workflow

🚀 Key Features Implemented

  1. Multi-module Architecture: Clean separation between API definitions and application
  2. TypeSpec-First Approach: API definitions drive code generation
  3. Version Management: Automatic version injection from VERSION file
  4. Interactive Documentation: Swagger UI with version selection
  5. Code Generation Pipeline: Automated model and interface generation
  6. Build Integration: Seamless integration with existing Gradle tasks

🔄 Migration Path

  • Zero breaking changes to existing API endpoints
  • Current API classes remain unchanged and functional
  • Generated code in separate packages to avoid conflicts
  • Gradual migration path available for future API evolution

📋 Tasks and Dependencies

All build tasks and dependencies now match app-bootstrap standards:

  • installTypeSpec: Install TypeSpec dependencies
  • generateOpenApi: Generate OpenAPI specs from TypeSpec
  • generateSwaggerUI: Create Swagger UI documentation
  • generateApiCode: Generate server interfaces and models
  • cleanApiCode: Clean generated code

🧪 Test Plan

  • Project builds successfully with new structure
  • /openapi endpoint serves Swagger UI correctly
  • OpenAPI specifications generate properly from TypeSpec
  • Generated code compiles without conflicts
  • Existing functionality remains intact
  • All build tasks execute successfully

🎯 Benefits

  • Maintainable architecture with clear module boundaries
  • Standardized workflow consistent with app-bootstrap
  • Improved developer experience with interactive API documentation
  • Future-proof design supporting API evolution and versioning
  • Automated code generation reducing manual maintenance overhead

This implementation establishes Wave as a reference example for modern API-first development with TypeSpec and provides a solid foundation for future API enhancements.

🤖 Generated with Claude Code

pditommaso and others added 6 commits September 1, 2025 23:38
@pditommaso @claude
Refactor project structure and fix OpenAPI endpoint
6ec343f 
- Restructure project into wave-api and wave-app modules
- Move existing API classes to wave-api module preserving current implementation
- Configure generated models to use io.seqera.wave.api.schema.v0 package
- Fix /openapi endpoint by removing controller redirect interference
- Update static resource configuration for proper OpenAPI documentation serving
- Remove old TypeSpec implementation in favor of new modular structure

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@pditommaso @claude
Align build configuration with app-bootstrap standards
78b3212 
- Add comprehensive OpenAPI configuration matching app-bootstrap
- Include useReactive=false, useAuth=false, and apiNameSuffix settings
- Add additionalProperties for consistent code generation
- Include missing jakarta.annotation dependency in wave-api module
- Ensure consistent task and dependency patterns across projects

This ensures Wave follows the same build patterns as app-bootstrap
for maintainable and standardized API generation workflow.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@pditommaso @claude
Fix GitHub Actions build failures
5ee3e83 
- Add explicit dependency for sourcesJar task on generateSwaggerUI
- Fix Gradle task ordering issue that caused implicit dependency warning
- Remove deprecated version property from TypeSpec @service decorator
- Resolve TypeSpec compilation warnings

This fixes the build failures in GitHub Actions by properly declaring
task dependencies and eliminating deprecation warnings.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@pditommaso
Keep compatibility with lagacy wave-api client
cd6d6c9 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso
Remove unused settings
b0165d2 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso
Fix failing tests
879d703 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso pditommaso mentioned this pull request Sep 2, 2025
Closed
@pditommaso
Merge branch 'master' into refactor-project-structure
051071c 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso
Update build deps
b9c38cf 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso
Rename package name from v0 to v1
3b0315c 
Signed-off-by: Paolo Di Tommaso <[email protected]>
@pditommaso
Fix swagger ui generation
f61049d 
Signed-off-by: Paolo Di Tommaso <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@pditommaso