Note: This post was cross-posted from Hexmos Journal
As I work on LiveAPI day in day out, trying to make it a tool worthy of people's time and attention - I keep thinking about what makes LiveAPI different from Swagger et cetera. What truly differentiates LiveAPI from the rest?
How Swagger/OpenAPI Is Used (As Of Now)
The easiest way to define what LiveAPI is, via a contrast with Swagger et cetera.
Both LiveAPI and Swagger cetera can produce the same output: a static HTML page that documents an API.
But how do they get there?
With Swagger et cetera the process goes something like this:
- The first task is to get an OpenAPI Specification. Write it manually, or plug some open source library into your codebase, and trust it to generate the specification.
- Setup a CI/CD pipeline to convert the specification into a static HTML page.
- Find a way and place to host the static HTML page.
- Configure a domain, take care of its access security, and point it to the static HTML page.
- Keep the library up to date, and keep the CI/CD pipeline humming.
The above process is repeated for every API service or project you may have.
Putting it this way - the process is tedious, error prone, and requires a lot of maintenance.
It's Not Just About Swagger - All Swagger Alternatives Take A Similar Approach
We recently wrote a small piece on 10 Top Swagger Alternatives for API Documentation.
As one goes through the list of alternatives, it is clear that most tools have one thing in common: most of them demand quite a bit of manual work.
In my team, we believe that the automation level offered is good, but there is huge room for improvement.
An enormous practical impact can be made if we can automate more of the API related processes, especially with AI-Powered automation.
The Purpose of API Documentation
I believe clear API documentation is key to high organizational effectiveness in orgs with more than one API service and more than one team.
Your engineers need discoverability, they need to know what APIs are available, what they do, and how to use them.
The engineering leaders need a birds-eye view of the API under their responsibility, and need to keep the conventions clean, have a good estimates of the various statistics related to the APIs, and so on.
Front-end engineers need to be able to quickly get started with new APIs.
And testers need to be able to run an API through a gauntlet of combinations of request parameters, headers, and body content.
Of course - if it is a customer facing API, you need to make sure that the documentation is good enough for the customers.
There are many potential consumers for API documentation, and it can make a huge difference in the effectiveness of an engineering organization.
Maxing Out The Automation Level
With LiveAPI, we are trying to max out the automation level.
To start with, we have picked a very particular problem statement:
Given a code repository, can we automatically generate excellent API documentation?
When I say automatically, I mean - no one has to lift a finger.
You connect your code repositories to LiveAPI, and we take care of the rest.
Every important commit - we update your API documentation automatically.
You don't have to add any custom code or library to repository to get LiveAPI integrated - just a few clicks will do.
You don't have to setup a CI/CD pipeline, or a static HTML page, or a domain, or access security worries.
LiveAPI takes care of all of that.
It is this level of extreme automation and convenience to the customer is what we are going for.
Whenever my team tries to start even a form, an extra step - I make an effort to question, and automate it away.
Why should the customer toil - when the potential of our present technology offers ways to automate so much?
LiveAPI Is The Electric Pump For API Documentation
In the near past - people used to draw water out of the well with a bucket, a rope and bare hands.
The quantity of water they could draw was limited by the strength of the human.
And this severely limited the quality of life - one'd think twice before taking a good bath, probably.
Then came the time when the electric pump was invented.
And everything changed.
People could now draw water from the well without any physical effort.
And the quality of life shot up.
You could have a good bath, without worrying about the quantity of water you have stored up via hard work.
Similarly, LiveAPI is the electric pump for API documentation.
It allows you to document your APIs - without any manual effort.
And I believe - with this sort of convenience and automation, the quality of life for various stakeholders in an organization will go up significantly.
Documentation will no longer be an obstacle, a headache - but rather an enabler, a facilitator.
And I believe - that is the sort of difference LiveAPI makes.
Top comments (0)