My favorite API testing tool is PAW, it's super light-weight and intuitive to use, almost zero learning curve. I've paid for my personal license and have been using it extensively ever since.
Until, when I need to publish documentations. Postman's documentation integration beats all other free tools in simplicity, integration, and look-and-feel.
For simplicity, you can quickly publish your API collections using built-in "publish to web" feature. For the APIS project, we have multiple collections: native RPC call collections, and our own Unified-Core endpoints, etc. Postman allows developers to group them under folders and it's super easy to move endpoints around.
For integration, you can set up variables for both environments or actual params. Typically, you can set up the {{hostname}} variable, so it'll be easy to toggle between localhost and your dev or production environments. The other typical use case is for auth tokens, you can set it up in a variable so all endpoints can get the value.
As for the look-and-feel, I know it differs from person to person. I prefer the Postman documentation page over the swagger-ui. Postman also allows developers to customize the documentation UI. It'd be nice if it has the light-mode and dark-mode out of the box, but maybe I'm asking too much. 😬
It almost sounds like I'm advertising for Postman. It's only fair to point out the biggest issues I have with Postman--it is built for collaboration, but the way Postman handling the free-tier collaboration is EXTREMELY APPALLING.
Postman auto archives your collections in a collaborative workspace, it won't restore it until you pay, and you need to restore it manually even after you pay. The archiving is done automatically when you are over the threshold and it's done silently! Well, it does email you on their action but it's already too late when you see the email.
The only way to fix that without paying is to export the collection, re-import them back to your personal workspace. Postman, as a company, is already so huge they can come up with more "humane" way of forcing developers to upgrade to the pay tier, in my opinion. I have become a paid user after suffering the trauma, so I guess that tactic is effective, at least on me.
Here's the quick link to the doc on publishing your API documentations:
https://learning.postman.com/docs/publishing-your-api/publishing-your-docs/
Top comments (0)