This was the commit message typed into my console when I decided that fighting with Swagger just wasn’t worth it anymore.
If you’re here reading, welcome! I’ve been logging my progress (almost) daily on my new side-project Roast, an app to help me track my home roasts.
For the past couple of days, I’ve been singing the praises of Swagger and OpenAPI and the ability to automatically generate a server.
But, today, I finally ran into ceiling with it.
Why I Chose to Abandon Swagger's Server
The reason is really basic actually: lack of flexibility.
After spending probably about two hours looking for a way to implement express-session, or any other custom middleware for that matter, I realized that this has been an issue with Swagger/OAS generated servers for some time.
I messed around with a few plugins here and there that attempted to generate routes from my OAS file, but I found that these tools just didn’t do as great of a job in the routing aspect of the project.
My routes were unreachable, every request that I would send responded with a 404, but I knew the server was running because I could still reach my generated /docs page that would update to changes in my YAML file.
Two Steps Back
I eventually hit the end of my rope, and just decided to restart the index.js file all over again. It was here that I realized just how much Swagger had done for me:
- Handled routing
- Extracted query and url parameters and automatically passed them into my controllers and services
- Created the framework for the controllers and services themselves.
- Parsed my request bodies and automatically passed them into my controllers and services
Was I really going to have to remake all of the functions and start from scratch?
What Can Be Salvaged?
I realized, that even though the Swagger generated server really wasn’t going to work for this project, there was nothing actually wrong with the controllers, or the service files for that matter!
All that I needed to replace was the entrypoint, index.js , routing and create some custom middleware to parse the bodies that I came up with.
What's the Lesson?
After it was all said and done, once I decided to just move forward with my own solution, the work took maybe 15 minutes to get the API back to the state that it was in before I left.
I created a routers/ directory and added router files for both of my tag groupings. And then, by manually pulling out the parameters that I needed and passing them into the controller functions, I was able to hook my new server into the controller/service model that had been set up for me.
Sometimes finding the solution to your problem will involve admitting that the direction that you were going was wrong.
I was dead-set on getting the generated server to work as it had come out, while only making changes to the controllers and services. I still saved a TON of time on the setup and boilerplate using the model, in fact, I’ll even be able to serve the docs using third-party node module.
And now, I have even more flexibility to integrate whatever middleware I want, rather than being locked into what Swagger wanted me to do.
I wouldn’t have been able to do this if I hadn’t learned how to build an express server on my own. CodeGen tools are great as a time-saver, but not as a knowledge replacement!
Check Out the Project
If you want to keep up with the changes, fork and run locally, or even suggest code changes, here’s a link to the GitHub repo!
The frontend application is currently deployed on Netlify! If you want to mess around with some features and see it in action, view it on a mobile device below.
Note: This deployment has no backend api, so accounts and roasts are not actually saved anywhere between sessions.