Evaluating @hey-api/openapi-ts For OpenAPI 3.1 Support

Hey guys! So, we're diving into the world of API generation, and the main goal is to evaluate @hey-api/openapi-ts to improve our support for OpenAPI 3.1 and JSON Schema 2020-12. This is a frontend/codegen spike, and we'll be looking at how well this tool fits into our current setup and what kind of impact it'll have on our workflow. It's all about making sure we're using the best tools for the job, and this evaluation is a crucial step in that process. Let's break down what this involves and what we're hoping to achieve.

The Spike's Scope: What We're Actually Doing

Alright, let's get down to brass tacks. What exactly are we doing during this spike? First off, we're going to add @hey-api/openapi-ts as a dev dependency. This means we're bringing in the tool that we're going to be evaluating, ready to get our hands dirty. We'll also set up an alternative generation script, giving us the ability to generate API clients using this new tool. The key is to keep our current imports untouched while we're testing this out. That way, we can see how the new generated code plays nicely with what we already have.

Next, we'll generate the client code. Specifically, this code will land in frontend/src/shared/api/generated-next. We're creating a separate directory to keep things organized and to minimize any disruption to our existing setup. We want to ensure we can easily compare the new output with our current code. This step is about getting the code generated and ready to go so that we can take a closer look at the changes and how it impacts the rest of the project.

After generating the client, we're going to run our standard build, test, and typecheck commands: pnpm build:frontend && pnpm test && pnpm typecheck. This is how we confirm that everything is working as expected. This step is vital because it ensures our build process runs without any problems and that we don't introduce any new issues that could break our existing functionality. This is where we make sure we’re not breaking anything while we are testing the new stuff.

Finally, the most important part: documenting the differences. This involves figuring out any changes in types or signatures and any impact it might have on how we work. This is the heart of the evaluation; we want to thoroughly understand the differences between our current code generation and what @hey-api/openapi-ts provides. By documenting the differences, we'll gain a solid understanding of the implications of switching to the new tool, helping us decide whether or not to adopt it. This is where we really figure out if this tool is the right choice for us, and if so, how we can make the switch.

Acceptance Criteria: What Makes This a Success?

So, how do we know if this spike has been successful? We have some pretty clear acceptance criteria. First and foremost, we need a green build, test, and typecheck. That means no errors, warnings, or anything that could break the system. The generated-next directory must be present, confirming that the code was generated correctly. This is the first signal that things are working as planned.

Then, there's the summary of changes and an adoption plan (or a decision not to migrate). This is the meat of the evaluation, guys. We need to document everything. This includes any differences in types and signatures, along with the implications for our codebase. And based on that, we'll have a clear recommendation, either to adopt @hey-api/openapi-ts and how to do it or to stick with our current system. Ultimately, the success of this spike depends on how well the new code integrates with our existing project. This is where we create a path forward and help us decide what we need to do moving forward.

Diving Deeper: Why This Matters and What We Expect

This spike isn't just about trying out a new tool; it's about setting ourselves up for future success. OpenAPI 3.1 and JSON Schema 2020-12 are the latest standards. Ensuring our tools are up to date helps us stay on the cutting edge and take advantage of all the improvements and features. This is about staying ahead of the curve, guys, and making sure our frontend is ready for what's coming next. By evaluating @hey-api/openapi-ts, we're taking a proactive step to ensure our API client generation is top-notch.

We anticipate a few potential outcomes. First, @hey-api/openapi-ts might offer better type safety, improved code generation, or more features that align with OpenAPI 3.1. We expect to see enhanced code quality and better support for the latest specifications. Another possibility is that the tool might bring additional capabilities to handle more complex API definitions, which could simplify our development workflow. The ability to handle intricate schemas can significantly boost productivity.

On the other hand, there might be some challenges. The tool may introduce breaking changes, or it might not integrate perfectly with our existing setup. The adoption could mean refactoring parts of our code, or it might require some extra setup to get everything running smoothly. The goal is to identify all these hurdles so we can prepare for them ahead of time.

Detailed Look at the Tasks and Deliverables

Let's break down the tasks in more detail so you can see exactly what needs to be done. First, we'll install @hey-api/openapi-ts and set up the generation script. This means adding the dependency, updating our package.json with the necessary scripts, and configuring the tool to work with our OpenAPI files. Getting the initial setup right is the first step toward a successful integration.

Next comes the client generation. We'll specify the output directory, and then we'll run the generation command. This involves making sure the tool correctly reads our OpenAPI definitions and generates the corresponding TypeScript code. We need to verify that all models, API endpoints, and data types are generated correctly and align with our current API definitions. This step will produce the actual client code we'll use in our frontend applications.

After generating the client, the most important part is the comparison and analysis. We'll examine the generated code, paying close attention to any changes in types, signatures, and code structure. We will need to compare the old and the new generated code to figure out what's different. We'll look at the differences and the impact they might have on our projects. We have to analyze the strengths and weaknesses of @hey-api/openapi-ts compared to our existing system.

Then, we'll run the build, test, and typecheck commands. This is about ensuring our project is still stable and that there aren't any hidden errors or regressions. We have to make sure the code compiles without errors, our tests pass, and there are no type errors. This step is about guaranteeing that the changes we have made haven't broken anything and that the generated code plays well with our existing frontend.

Finally, we'll create the documentation and make a decision based on the results. We will create a comprehensive document that describes the differences, the advantages, and the disadvantages of @hey-api/openapi-ts. This documentation will serve as a guide and roadmap for anyone using the tool in the future. Based on the evaluation, we'll have a clear recommendation, either to adopt the new tool or to stick with our existing one. This final step is where we formalize the evaluation and make sure the team knows what to do moving forward.

Potential Challenges and How to Address Them

There's always a possibility that we'll run into some snags, but we're prepared to handle them. Compatibility issues could be a major challenge, particularly if @hey-api/openapi-ts isn't fully compatible with our current project's setup. This might require us to make some tweaks to the configuration or even modify our existing code to make sure everything works correctly. To handle these issues, we'll consult the documentation, check online forums, and seek help from the @hey-api/openapi-ts community. The community is an excellent resource for any potential problems.

Integration with the existing codebase could also be an issue. Merging the new generated code with our existing codebase can lead to merge conflicts, or we might need to update our import statements or modify existing files to use the generated code. We can reduce these risks by carefully planning the integration process and by making incremental changes rather than trying to do everything at once. This strategy is also more likely to succeed.

Performance could also be a concern. The new tool may generate larger files or use different code generation strategies, which could affect the build times or the runtime performance of our frontend applications. To address these concerns, we'll test the performance of the generated code and compare it to the performance of our existing code. We have to check and then analyze the build times and any performance issues. Based on this analysis, we can make informed decisions.

The Expected Impact and Benefits

If we decide to adopt @hey-api/openapi-ts, there will be some huge benefits, especially in terms of maintaining the API client. The primary benefit is probably enhanced code quality and better support for the latest OpenAPI specifications. This will provide more robust and maintainable code. The updated tool can handle the complex OpenAPI definitions. Also, it streamlines the API client generation and increases development efficiency.

By ensuring we can readily adapt to the ever-changing landscape of API standards, we're building a more scalable and flexible system. A key benefit is the reduction of manual effort and the decreased chance of errors. Another area is the automation of the entire process, which will free up development time, allowing the team to focus on core functionality. In addition, by adopting the tool, we will be able to easily update and maintain our API client. This is a game-changer for our development workflow.

Conclusion: Making the Right Call

So, by the end of this spike, we'll have a clear picture of whether @hey-api/openapi-ts is a good fit for our project. We will have a thorough understanding of the generated code, how it integrates with our existing system, and the overall impact it will have on our development workflow. This will help us to decide whether to adopt it or stick with our current tooling.

Ultimately, this evaluation is all about making the right choices for our team. We'll be able to improve code generation, increase development efficiency, and stay ahead of the curve in the world of API development. This is about making sure we have the tools we need to succeed. The decision will be based on a thorough understanding of the tool's capabilities. Based on our needs, we will be able to make the right choice to ensure we have the most efficient and effective system for generating our API clients.