DEV Community

Cover image for Using Postman For API Documentation: All You Need To Know

Using Postman For API Documentation: All You Need To Know

Dumebi Okolo on July 31, 2024

In my previous article, Docs As Code: The Best Guide For Technical Writers, I talked about the concept of Docs-as-code and gave a deep dive into it...
Collapse
 
mjac profile image
Mitch Jackson

Be aware, postman copies your project data to their cloud where they will pinky swear keep it safe and private. They've changed their product to be so aggressive about sending themselves your data that it's easy for their product to cause a compromise. Ever since they made these changes, I'd not want to ever enter live or test credentials into their software.

We recently had a dev at an integration shop we hired accidentally publish API keys and non public api specs to a postman public web project, because they didn't realize postman was putting all their work online.

Collapse
 
dannydainton profile image
Danny Dainton

We don't recommend that any users hardcode any tokens or sensitive data in there Workspaces or the elements within them, there is messaging and warning in a number of places to discourage users from doing this.

Ensure that you use variables and place data that you don't want to sync, only in the current values of the variable.

We recently introduced the Postman Vault which is available to all users, to locally store encrypted sensitive data. These are only stored on your machine.

learning.postman.com/docs/sending-...

We also announced changes to enhance the security of data that can be made public by users, we already had the secret scanner in place that alerts users of sensitive data in Public Workspaces but now these are automatically delisted and removed from the Public API Network. More information about the other changes can be found here:

blog.postman.com/public-api-networ...

If users prefer a lightweight version of Postman which can be used offline and locally, we have the Lightweight API Client:

learning.postman.com/docs/getting-...

Collapse
 
dumebii profile image
Dumebi Okolo

Oh wow. I'm hearing that a lot of people actually don't like using Postman. It's very interesting to find out.

Collapse
 
sirzarganwar profile image
Martin Jirasek • Edited

I am using simple application Bruno usebruno.com
The app is much easier but very similar as Postman. You can simply keep every collection/request/scripts/... settings under version control.

Collapse
 
dumebii profile image
Dumebi Okolo

Okay!! I'd check it out ASAP. Thank you for sharing.

Collapse
 
liyasthomas profile image
Liyas Thomas

If you'd like to try an open source { free } alternative to test APIs, try Hoppscotch - API request builder for web : hoppscotch.io

GitHub logo hoppscotch / hoppscotch

Open source API development ecosystem - https://hoppscotch.io (open-source alternative to Postman, Insomnia)

Collapse
 
debs profile image
bbbb

I don't recommend hoppscotch because it doesn't support git integration, managing collections as files, or self-hosted logins. Try bruno instead.

Collapse
 
liyasthomas profile image
Liyas Thomas

We're working on implementing Git friendly, file-based workspaces. Stay tuned for the next couple of releases!

Thread Thread
 
dumebii profile image
Dumebi Okolo

I'd definitely try out hoppscotch and let you know what I think.

Thread Thread
 
debs profile image
bbbb

said were going to improve the desktop app in Q1 2024, but now it's Q3.

Collapse
 
dumebii profile image
Dumebi Okolo

Hmm. Okay. I'd take a look at that

Collapse
 
asologor profile image
Andrew Sologor • Edited

I hate Postman. It has so many annoying bugs and its interface is flooded with all the unnecessary bullshit. I use it only for GraphQL APIs. My personal favorite API client is Insomnia, though it's bad for GraphQL yet.

Collapse
 
dannydainton profile image
Danny Dainton

If all you need is a GraphQL client to build requests and test your endpoints, you could just use the Lightweight API Client instead.

learning.postman.com/docs/getting-...

If there are specific issues or bugs that you'd like to raise, you can do that here:

github.com/postmanlabs/postman-app...

We're always here to listen to constructive feedback and can improve what we offer to our users.

Collapse
 
asologor profile image
Andrew Sologor

I'll check it out, thanks.

Collapse
 
asologor profile image
Andrew Sologor

The lightweight client does not have environments and does not allow creating request collections. It's freaking useless. You added the cloud sync and forced users to use it by removing the core necessary features from the local (lightweight) version. Now it has 100500 bugs like:

  1. Renaming a request reverts its prev name back immediately
  2. Opening a collection shows preloader instead of the requests and the requests won't load until restarting the app
  3. Refreshing the GraphQL schema gives an error until restarting the app
  4. The weird one: naming an env var "base_url" resolves the value to some "example" domain (that hosts an example GraphQL schema), even though it shows the correct URL in the UI. Changing its name to anything else works as expected.

And it's not the full list of what I found.
My feelings toward Postman are the same as to Internet Explorer 10 years ago. I wish it didn't exist, but unfortunately, there's no better GraphQL GUI at the moment.

Collapse
 
dumebii profile image
Dumebi Okolo

Oh really? I haven't tried Insomnia yet!
I'd definitely do that.
Plus, Postman isn't so bad tbh.

Collapse
 
christoferd profile image
Chris De David

Can it export documentation for your tests?
That's what this article is about.

Collapse
 
anmolbaranwal profile image
Anmol Baranwal • Edited

I don't document it because I didn't know about it :)

But I do create collections, workspaces, and variables, name the requests, and arrange them properly so it's easier to work with.

By the way, have you tried Hoppscotch? A lot of people have moved from Postman to that (except me) 😅

Collapse
 
dumebii profile image
Dumebi Okolo

Oh really? I guess that's what I'm trying out next!
My plan is to use a lot of platforms and write about them so that others can learn as well.

Collapse
 
ashleyd480 profile image
Ashley D

Wonderful share @dumebii! This will be a lot of help when I'm writing out my backend methods and testing on Postman. I like how we can document as we go, and by the end of it- we have great documentation to reference and share! ❤

Collapse
 
dumebii profile image
Dumebi Okolo

Yaaay. Awesome! 🥳

Collapse
 
qaengineering profile image
qaEngineering

Great article, we heavily use this documentation feature.

I also recently discovered an open source tool that i am currently learning and experimenting with in my free time - FlowTestAI.
github.com/FlowTestAI/FlowTest
useflowtest.ai/

What i noticed was that this tool is very different from existing tools in the market as it takes an end to end API testing approach. Because this tools translates things into a visual graph, these end to end flows can potentially act as your live documentation.

Also it allows to create end to end API tests using natural language via LLMs which makes job for us QA people very easy as we don't have to read and understand openAPI specs anytime a new endpoints are released for testing

Collapse
 
dumebii profile image
Dumebi Okolo

Oh wow. That's a whole lot.
I'd be checking it out and writing about it soon.
Thanks for sharing!

Collapse
 
rebeccapeltz profile image
Rebeccca Peltz

Great topic! You opened up discussion that introduced a line of API products supporting documentation and testing. As much as I like Postman, learning about these other products is really helpful.

Collapse
 
dumebii profile image
Dumebi Okolo

Thank you so much! I'm glad you found this helpful.

Collapse
 
ukaypromise profile image
Engr. Promise

Awesome 👍😎

Collapse
 
dumebii profile image
Dumebi Okolo

Thank you!

Collapse
 
gowthamkasi profile image
gowthamkasi

apidog.com/

Postman alternative better than postman in terms of documentation

Collapse
 
dumebii profile image
Dumebi Okolo

Oh really? I'd definitely check it out!