DEV Community

Cover image for API Documentation Tools: Using Postman For API Documentation
Dumebi Okolo
Dumebi Okolo

Posted on • Updated on

API Documentation Tools: Using Postman For API Documentation

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.
Before starting as a Documentation Engineer, I didn't know much about API documentation. The take-home task I was given by the company was to document the endpoints of an API given to me. I took this journey and began learning about API documentation and the different tools for documenting API.

I will be sharing all that I have learned so far.

Why do you need API Documentation?

APIs (Application Programming Interfaces) play an important part in empowering software systems to communicate and interact effectively. Proper API documentation is needed for developers (or whoever will come across the documentation) to understand and utilize these APIs.
One of the tools that has become a favorite Postman.

Table of Contents

 1. 1. What is Postman for API documentation?

       1.1. Why Use Postman for API Documentation?
 2. 2. How to Set Up Postman For API Documentation

       2.2. Steps to Install Postman for API Documentation
 3. 3. Steps For Creating API Documentation in Postman

       3.3. What is a Collection in Postman?

       3.4. Step 1: Create a Collection

       3.5. Step 2: Add Requests to Your Collection

       3.6. Step 3: Document Each Request

       3.7. Step 4: Generate and View Documentation
 4. 4. Best Tips For Organizing Your Documentation in Postman

       4.8. Use Folders in Postman

       4.9. Use Environments in Postman

       4.10. Use Variables in Postman
 5. 5. Sharing and Collaborating in Postman

       5.11. Share Collections

       5.12. Use Team Workspaces

       5.13. Commenting and Version Control in Postman
 6. 6. Top 5 Best Practices for API Documentation

       6.14. Be Clear and Concise

       6.15. Include Examples

       6.16. Keep It Up to Date

       6.17. Use Descriptive Names

       6.18. Utilize Postman Features
 7. 7. Conclusion

1. What is Postman for API documentation?

Postman is a collaboration platform for API development. It simplifies each step of building an API and streamlines collaboration so that you can create better APIs—faster.

Why Should You Use Postman for API Documentation?

  • User-Friendly Interface: Postman's intuitive interface makes it easy for developers of all skill levels to create, test, and document APIs.
  • Comprehensive Features: From automated testing to monitoring and collaboration, Postman offers a wide range of features that enhance the API development process.
  • Collaboration Tools: Teams can share collections, environments, and documentation, facilitating better collaboration and consistency.

2. How to Set Up Postman For API Documentation

To get started with Postman, you need to install the application on your computer. Postman is available for Windows, macOS, and Linux. You can download it from the Postman website.

Steps to Install Postman for API Documentation

  1. Download Postman: Visit the Postman website and download the appropriate version for your operating system.
  2. Install Postman: Follow the installation instructions specific to your OS.
  3. Sign Up/In: Once installed, open Postman and sign up for a new account or log in if you already have one.

3. Steps For Creating API Documentation in Postman

Creating API documentation in Postman involves a series of well-defined steps. Here's how you can do it:

What is a Collection in Postman?

A collection in Postman is a group of requests.

Step 1: Create a Collection in Postman

To create a collection:

  1. Click on the Collections tab in the sidebar.
  2. Click the New Collection button.
  3. Name your collection and add a description if needed.

Create a collection in postman

Step 2: Add Requests to Your Collection in Postman

Within your collection, you can add individual API requests:

  1. Click on your collection to open it.
  2. Click Add a request.
  3. Name your request and specify the HTTP method (GET, POST, PUT, DELETE, etc.).
  4. Enter the API endpoint URL and any required parameters.

Step 3: Document Each Request

For each request, you can add detailed documentation:

  1. Click on a request to open it.
  2. Click on the Documentation tab.
  3. Add a description, including details about the endpoint, parameters, headers, and sample responses.
  4. Save your changes.

How to add documentation in postman

Step 4: Generate and View Documentation in Postman

  1. Go to your collection.
  2. Click the ... (three dots) menu next to your collection.
  3. Select View Documentation. This will open the documentation view within Postman.

View documentation in postman

For a shareable web version, you need to publish the documentation.

Publish documentation in Postman

4. Top 3 Tips For API Documentation in Postman

Organizing your API documentation is the best thing to do. This will aid clarity and usability. Thankfully, Postman provides several features to help you keep your documentation well-structured:

Use Folders in Postman

Folders allow you to group related requests within a collection. To create a folder:

  1. Right-click on your collection.
  2. Select Add Folder.
  3. Name your folder and add requests to it.

Use Environments in Postman

Environments enable you to manage different sets of variables. For instance, you might have different environments for development, staging, and production. To create an environment:

  1. Click on the Environments tab in the sidebar.
  2. Click Add.
  3. Define your variables and save the environment.

Use Variables in Postman

Variables can be used to store values like URLs, tokens, or any other data that may change. This makes your requests reusable and easier to manage. To use variables:

  1. Define them in an environment.
  2. Reference them in your requests using the {{variable_name}} syntax.

5. How to Share and Collaborate for API Documentation in Postman

Postman excels in enabling team collaboration. Here are some ways you can share and collaborate on your API documentation:

Share Collections

You can share collections with your team:

  1. Click on your collection.
  2. Click the Share button.
  3. Choose how you want to share (via link, in a team workspace, etc.).

Use Team Workspaces

Team workspaces allow multiple users to collaborate in real-time. To create a team workspace:

  1. Click on your workspace name at the top left.
  2. Select Create Workspace.
  3. Invite your team members.

Commenting and Version Control in Postman

Postman supports commenting on requests and tracking changes, ensuring that everyone stays on the same page.

6. Top 5 Best Practices for API Documentation in Postman

To make the most of Postman for API documentation, consider the following best practices:

Be Clear and Concise

Ensure your documentation is easy to understand. Use clear language and avoid unnecessary jargon.

Include Examples

Provide examples of requests and responses to help users understand how to use the API.

Keep It Up to Date

Regularly update your documentation to reflect any changes in the API.

Use Descriptive Names

Name your collections, requests, and variables descriptively to make it easier for others to understand their purpose.

Utilize Postman Features

Take advantage of Postman's features, such as mock servers, monitors, and automated testing, to enhance your API documentation.

7. Conclusion

In conclusion, Postman is an incredibly powerful tool for API documentation. Its user-friendly interface, comprehensive features, and robust collaboration tools make it an ideal choice for developers and teams. By following the steps and best practices outlined in this guide, you can create clear, concise, and effective API documentation that will greatly benefit your API users.

Whether you are a solo developer or part of a larger team, leveraging Postman for API documentation can streamline your development process and improve the overall quality of your APIs.

Let's connect on LinkedIn! ❤

Top comments (29)

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
 
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!

Collapse
 
ukaypromise profile image
Engr. Promise

Awesome 👍😎

Collapse
 
dumebii profile image
Dumebi Okolo

Thank you!