Fuego 2025 Roadmap : incremental adoption for Gin/Echo...

[EwenQuim]

What a year for Fuego! 🔥 What about the next one?

Hello Maintainers, Contributors, Sponsors, and visitors!

As 2024 comes to a close, we’re proud to celebrate some incredible milestones:

• almost 1 000 stars on GitHub
• 30 contributors
• Nearly a year of production use across several teams worldwide
• 500+ tests of every configuration possible in our CI
• A talk at the API Days Paris 2024 !

Fuego has proven to be a game-changer, delivering efficiency and utility for developers everywhere. But we believe there’s even more potential to unlock. We've noticed that adopting Fuego for new projects doesn't cause any problems, but that in reality, many existing projects would like to adopt Fuego without having to change everything.

1️⃣ Fuego as a pluggable OpenAPI framework

Migrating from Gin/Echo to Fuego is hard

For teams building on frameworks like Gin or Echo for years, migrating to Fuego is purely impossible. We understand that rewriting a mature codebase isn’t always feasible—but achieving a 100% accurate OpenAPI declaration might still be a priority.

Proposed Solution: native controllers OpenAPI wrapper

These will allow users to still use their favorite routers while integrating Fuego’s OpenAPI generation. Think of it as having the best of both worlds: keeping your familiar setup while supercharging your API documentation. It's not a superset, but a library: composition over inheritance. And we're already working on this (#262 #241 #260...). Expected in early 2025!

2️⃣ Strongly typed params?

When migrating, it's easy to lose information when params are not typed

We moved from #119 to #174 for several compelling reasons: improved reusability, enhanced composability, and greater customization flexibility. However, this shift came with a significant trade-off: it challenges one of Fuego's core promises—that all server-side code aligns perfectly with the OpenAPI specification. The issue arises when the registered options don’t match those used in the controller, leading to only a runtime warning in the logs. While this may suffice when creating & testing new controllers, it becomes a potential pitfall during a large-scale codebase migration, where it’s easy to overlook a parameter.

Proposed Solution: Typed Parameters & Variadic Options for Non-Parameters

To address this, we propose a balanced approach: reintroduce typed parameters to ensure stricter alignment with the OpenAPI specification while retaining variadic options for metadata such as Description, Summary, Tags, and Middlewares. This solution allows developers to benefit from both precision and flexibility.

Typed parameters will provide strong guarantees that all necessary data is explicitly defined and validated, minimizing the risk of missed parameters during migration. At the same time, keeping non-parameters as variadic options maintains Fuego’s hallmark composability and extensibility, enabling developers to customize their controllers without losing control over critical API elements.

This approach not only preserves Fuego’s original philosophy but also enhances its usability for both new projects and legacy codebase migrations.

3️⃣ OpenAPI 3.1 & 3.2

Fuego already generates a valid OpenAPI 3.1 description since v0.14.0. We just need to deprecate Nullable, I think it is the last easy step to fully support 3.1 (OpenAPI 3.1 migration guide).

We're looking forward to support 3.2 day one (or before!).

What about original Fuego philosophy?

Fuego will evolve to support two primary usage modes: as a framework for new projects and as a wrapper for existing codebases. No matter how you use it, we’re committed to upholding Fuego’s core philosophy:

• Don’t Get in the Way:
  Fuego will never abstract away the underlying router, whether it’s net/http, Gin, Echo, or another framework. Controllers will feel familiar and consistent, with only ctx.Response() and ctx.Request() exposing the native router directly.

• Composable & Extensible:
  By retaining variadic options, we empower developers to make choices that fit their needs. Importantly, variadic options and strongly typed parameters don’t have to be at odds. We envision a balanced approach where options handle metadata like Description, Summary, Tags, and Middlewares, while strongly typed parameters (Query, Headers, Cookies) ensure clarity and precision. This combination offers flexibility without compromising Fuego’s core principles.

• Always Latest OpenAPI Spec:
  Fuego will ensure that APIs always conform to the latest OpenAPI specification, maintaining modern standards and enabling seamless integration with the broader API ecosystem.

• Backward Compatible:
  We prioritize backward compatibility by avoiding breaking changes wherever possible. When breaking changes are unavoidable, they will never be silent, ensuring clear communication and migration paths for developers. This approach safeguards stability and fosters trust as Fuego evolves.

When will all this happen?

First, we need to open up discussions and gather feedback from the community. While there’s still work ahead, our goal is to release these updates before summer 2025. To achieve this, we need to act quickly and collaboratively.

Additionally, we’re committed to ensuring these improvements are backwards-compatible, so existing users can adopt the changes seamlessly without disrupting their workflows.

We need YOUR help! 💪🏻 Yes, you, don't be afraid!