What happened?
So I work on a team of 2, just myself and one other lucky soul that gets to enjoy my constant foot tapping and head bobbing as I dance to my headphones and clack away at my keyboard, creating beautiful code.
Well yesterday, I had a coworker come to me and ask me for help with issues he had using my api and npm module. Being I was the main person on the project, it made sense that he would come to me for help.
As I got into his code and saw how he was using my module, as well as the api, this was when I realized that I only halfway provided documentation.
It's 2 part, an npm module for aws-sig4 which will allow easy connecting to our lambda api. I did a great job documenting the module but failed at documenting the api.
Why did it happen?
We were somewhat rushed on the project. It was a simple 2 endpoint api with a few attributes for each, but it had to be setup as a lambda service, behind a gateway and fully automated via terraform and the ci/cd pipeline via gitlab.
If any of you have dealt with automating the setup for aws and the pipeline for ci/cd, you know this is a huge amount of work.
But even with the deadline, Why didn't we think to use OpenApi or another api spec, especially since this is pretty standard for our other projects.
Honestly it was probably due to the mindset "get it done by the deadline" and dealing with the headache of automated deployment.
Ya, but you still failed at documenting!
I could make excuses all day as to why I failed to document this api properly and even if they are valid, it doesn't change the end result.
The developer using the api, didn't have enough information to know if what they provided was correct, which fell back on my lap which caused extra unexpected work for me.
How do we do better next time?
So how do you document an API? Well glad you asked!
There are many way and choices, which I encourage you to feel free to explore those. My answer is not a fact, it's a preference.
I lean heavy on https://swagger.io/
With their OpenApi spec (formerly Swagger Specification) you can design your api exactly how you want it before you ever touch a line of code.
The benefits you will gain from this, is that you can have a single document of truth for not just developers but also your frontend devs. That is just one very important benefit, but there are more!
There are many tools that will take the spec and give you additional functionalities. See a few below.
- generate interactive docs such as Swagger UI, see Swagger UI demo
- generate your server stubs and client libraries (check out Swagger Codegen)
- Test your live endpoints against the spec, using libraries like Dredd
If you want full list, you can find them at OpenAPI.tools
That is great, but is there a quick start?
- Go to OpenApi spec v2 and learn the spec. ~Note~: there is v3 but not everything supports is yet (it's cool to use it, just be mindful)
- Write your first spec
- Setup Swagger UI and connect your new spec
- Pat yourself on the back for learning something new
- Explore, learn more and improve
- Come back and teach me something you learned!
Top comments (0)