Im starting my journey into OpenAPI and I think its the answer to a problem I didn't know I had!
The problem I hadn't noticed before
How many times have you wrote the backend API then the Frontend API Layer then the docs, Normally thats 3 peoples jobs or one if you are unlucky, but then you and the team have to keep that all up to date, its not easy, actually its a big bottleneck in development time and therefore cost.
So what if we could just sit down together and write a single yaml, human readable file that anyone could understand. A file single powerful file that could generate the server code for our chosen language/framework, the client code and the docs all in one central location, if you think about it, this makes perfect sense and what a time saver... That is OpenAPI
Getting started from a real life example:
I started writing my web application to make a load of money. How did I start it? With Frontend as usual and then realised that this would be doomed to fail as I never get around to doing all the backend work, its too huge then Id need a team to document it for future me. I need an easy button.
I've dabbled with and wrote many types of code-generation software in node over the years and I believe strongly that its an enormous time saver if we accept standardisation, let go of some of our, but I didn't write it syndrome, code-generation brings predictable development and quicker time to first release, that means more time doing fun stuff and less time being tedious.
The Stack
Bun (API server) + Sveltekit (yes its fast with capital F, correct me if Im wrong but it should be Rust Actix web fast) the BS stack, it needs business logic right? I think it's time to read about this API design first approach, the glue between our Backend and our Client is the literal language they speak to each other, and by designing this instead first, we may have an easier time developing our application.
I will use a Frontend framework IBM Carbon and various other bits specific to my application.
What I did
- I watched some videos
- Found out about the generators for my chosen language ala the npm ecosystem
- Mulled over how I was going to write this api following the standard
- considered VS code but then dropped it for something more specialist: Insomnia
- While I have no bun generator I used a node OpenAPI mock generator server thing, I will have to manually copy and paste the structure, its a little overhead but at-least the tedium of the shape of it is done
- Now I can write using Insomnia DESIGN tab and copy that to my mock server via vs-code to try out
- The experience of having the entire API in a document really helps make it consistent and allows for thoughtful design
Here is Insomnia working on a early prototype, its making my head hurt now i'm running out of imagination and I think I need to build something!
Top comments (0)