Building requests

Last modified: 2023/06/07

Introducing The Good Documentation Checklist

' src=

LAST UPDATED ON: May 3, 2022

I’ve previously talked about the traits of a good collection . While not all collections grow up to be documentation, collections are the foundational building blocks for all Postman documentation viewable on the web. Here, I’m going to talk about the traits of good documentation.

Postman documentation has become widely adopted across the API community because it enables better collaboration and API adoption. Let’s learn from the thousands of publishers who document their APIs in Postman—like Microsoft , Twitter , and Dropbox —and find out what makes their documentation successful.

What is good documentation?

Effective documentation teaches someone how to use your API. Since the intended audience is people, and not machines, effectiveness is a subjective measure. Still, we can find some shared similarities across good documentation.

Take a look at this breakdown of nine helpful documentation tips and see how your own process measures up. In true Postman fashion, I’ve documented these guidelines in a collection. You can experience an interactive version of this blog post in The Good Documentation Checklist template, which is comprised of examples from publishers who document their APIs in Postman.

Interactive Good Documentation Checklist template

1. Create a Postman Collection

2. Organize the API metadata

Twitter API documentation with metadata, examples, and folders

3. Include a Getting Started guide

Dropbox documentation includes headings in the Introduction

4. Keep it DRY with variables

5. Show use cases

6. Be secure

7. Share private API documentation

8. Share public API documentation

Team profile page listing multiple collections in the Postman API Network

If you’ve ticked most of these boxes, then you can confidently say that you have good documentation . For all you overachievers, let’s forge ahead to a bonus round.

9. Advanced stuff

More examples of good documentation

If you’re looking for benchmarks of good documentation collections, check out these stars:

Many of the better practices we’ve talked about are universal truths about docs, whether or not you’re documenting your APIs with Postman. If you’ve read this far, chances are you’re thinking about investing in proper onboarding and developer education for your APIs.

Come on over and join the Postman API Network . Or dig deeper into documentation best practices and check out this post I wrote about The Ultimate API Publisher’s Guide . If you’re doing something neat with API documentation, let us know in a comment below so that we can share it with the rest of the Postman community.

' src=

Joyce is the head of developer relations at Postman. Culinary magician who specializes in tacos and boba. View all posts by Joyce.

What do you think about this topic? Tell us in a comment below.

Comment Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed .

' src=

Thanks for the good article

' src=

Wonderful..Awesome writing

You might also like

New documentation for the collection format.

' src=

When you think about Postman Collections, the first thing that often comes to your mind isn’t a JSON-based API specification. The first…

How to publish and market your API to maximize adoption

' src=

You’ve designed an API that is world-class. Now you might be wondering how you get users to start adopting it. If you…

Introducing more customization for published collection documentation

' src=

Postman has helped millions of users improve their API documentation workflow. For instance, collections enable teams to easily evolve their API documentation…

Postman named Best API Platform

Postman is the #1 place where developers come to work with APIs. See why we’re top-ranked in G2’s first-ever evaluation of API Platforms.

Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Creating html doc from postman collection [closed]

I've developed a pretty extense API, and I have it on Postman, which works pretty nice. Now I have to generate an html doc to keep it versioned inside /docs along with my sources.

Is there a tool or a way to achieve this? I really don't want to write all this documentation. Sharing the postman collection is not an option.

danielrvt's user avatar

4 Answers 4

I recently had the same problem and I did not find anything. So I created a simple tool to do it. It is a very basic javascript application written with react.js. At the moment it is very basic, but I'm working on it, so any feature request is welcome.

You can use it for free at:

Plus you can get the code and modify it at:

Any comment is more than welcome.

UPDATE1: looking around I also found this project: and this feature request:

UPDATE2: the feature request (see UPDATE1) has been closed and the possibility of creating documentation has been added to Postman cloud. Here is the feature request closing comment:

This is available as part of Postman Cloud: . Cloud hosts, updates and maintains documentation for everyone. I'd suggest and for generating one-time documentation from Collections.

Davide Vernizzi's user avatar

I know this is an old question and you probably found a solution by now, but still you might be interested by Postmanerator:

Basically, this is how you use it from the command line:

To get it installed, download the latest Github release. You need to pick the appropriate binary depending on your system. Then place it somewhere in your PATH.

See the documentation in the README if you want additionnal information. From there you will find recommandations for taking full advandage of the tool, or change the look of your documentation by using custom themes.

The Github presentation also provides a reference to a generated example documentation.

You will also discover how you can take advantage of a CI platform like Travis, to automate the generation and the publication of your documentation with Postmanerator.

As this is an open source project I'm currently working on, feel free to submit issues on Github if you have any ideas that can make it better.

kendo5731's user avatar

You can install Newman using command "npm install -g Newman" and then run the command "newman run CollectionName.json -e envVar.json" from the location where you have saved your collection, where CollectionName.json is your collection name and enVar.json is the set of environment variables. This will generate html report in the same folder. One prerequisite is to have node js installed.

Vandana Jayaprakash's user avatar

You can also try the free tool that I made. It provides the documentation in .txt but you can convert it to pdf using your browser.

Dennis Djan's user avatar

Not the answer you're looking for? Browse other questions tagged api rest documentation documentation-generation postman or ask your own question .

Hot Network Questions

how to write postman documentation

Your privacy

By clicking “Accept all cookies”, you agree Stack Exchange can store cookies on your device and disclose information in accordance with our Cookie Policy .

How to Document APIs With Postman

An API is only as good as its documentation, so make sure yours are easy to understand and use with Postman’s support.

Documentation is a critical aspect of the API development cycle. It helps consumers understand the functionality of your API and how they can interact with it. The documentation should explain how to make requests to an API, the parameters each endpoint supports, and the responses you can expect.

Modern API tools simplify the process of creating, testing, and sharing documentation, and one of these tools is Postman.

Postman is a popular cross-platform API development and testing tool. It provides you with a simple and efficient way to create, test, and share APIs and their documentation.

Why You Should Use Postman for Your API Documentation

Postman provides a user experience for testing APIs and creating interactive documentation. It lets you test an API directly from its documentation. This feature is useful for many operations, including checking if the API is running and working as intended.

Here are six reasons why you should consider using Postman for your API documentation project:

Getting Set Up With Postman

First, you’ll need to create a collection to group the requests for your API. You can create a collection from the Collections tab; make sure to name your collection.

After creating a collection, you can proceed to add the requests for your API and test the endpoints to ensure they work as intended.

Use the Save button at the top of the request tab to save each request that you configure to your collection.

After adding and saving requests to your collection, you can proceed to the documentation phase.

Documenting Your API

Postman provides an editing tool to document your API. Once you’ve selected the collection in the top right corner of the Postman app, click on the document button to access the documentation tool.

After opening the documentation tool, you can start writing your documentation. The editor supports Markdown syntax and provides tools for editing raw text.

Here’s an example of documentation for a GET request endpoint:

You can document your APIs based on specifications like OpenAPI to improve the quality and readability of your API documentation .

Once you’re done documenting your API, you can publish the documentation with the Publish button on the top right of the documentation view.

Postman would open a webpage where you can customize and style the API documentation.

Once you’re done configuring and styling your documentation, you can proceed to publish it. Postman will create a webpage where your users can access the documentation and test your API functionality.

Click the options button ( ... ) on the collections tab to generate your documentation in other formats.

You can find the documentation example for this tutorial on this Postman documentation webpage .

You Can Test Your APIs With Postman

Postman is a versatile, understandable tool that can ease the process of API documentation. You can also test different types of API, from REST to SOAP, GraphQL, and OAuth.

Postman also supports a wide range of API styles, including gRPC and WebSockets. All these features make Postman a great tool in your development arsenal.

API Documentation in Postman

Enroll in Selenium Training

Documentation in general terms is the written material that provides or serves as official evidence or information. When we talk about documentation, we are generally talking in terms of learning or gathering information about certain things. This depends on the subject of documentation. For example, documentation of a certain specimen in the laboratory will provide information about that specimen to the doctors . In the IT world, documentation of different software, tools, and APIs help you learn about those things from trusted sources ( official ) and in a correct way. This takes us to the API Documentation in Postman . To index our tutorial, we will learn:

How to Generate API Documentation in Postman?

What is api documentation in postman.

The API documentation is a well structured written material that provides third-party users to use the API efficiently . This includes the step-wise process and instructions on how to use your API. This documentation enables the third party users/developers to understand the usage of your API very quickly. Given below is the documentation for Paypal API


Writing API documentation requires a very good understanding of the API, its use, programming language used and response. Good API documentation should be able to convey the complex process in a simple and easy manner with good detailed instructions.

Why API Documentation is required and important to have?

As throughout this course we have learned how to use the APIs and execute tests on them. As you must recall, we used our own API to demo some of the features of Postman to you. Since APIs are constructed by every company which allows it to use them, they need a well structured official document to guide developers on how to use it. This is very important as what is the point of developing something great when nobody is able to use it? The API developing corporation is not the only user of its API. Third-party developers make a good percentage of users. Since API serves as a middleman to make use of the product, documentation serves as a platform to make use of API. Without good API documentation, the product cannot be used which in turn will incur a loss for the organization. This goes for small businesses, budding startups and individuals like you. Anyone who is willing to share his API must have documentation for the people to guide them. Therefore, API documentation is as important as an API and in our case, this is done by Postman. We will see how in the next section.

You can visit the API documentation pages I have mentioned here which are quite popular among the developers:

Paypal API Documentation

Twitter API Documentation

Facebook API Documentation

Trello API Documentation

API documentation using Postman

Postman helps us create API documentation with the help of a few clicks. It is a great way instead of writing your own documentation from scratch and publishing it on your own. Before we proceed to actually publish the documentation, you must make note of a few things.

It is not advisable to publish documentation without your company's knowledge. Once you sign in to Postman app, all your local collections and requests are synced to the Postman cloud. This will sync your documentation too as you cannot publish API documentation in Postman without signing in. In other words, your documentation will become public and will be accessible to anyone. To make your postman private, you need to be a Postman Enterprise or Postman Pro member. If you are, you can share your documentation within your team or organization privately.

You should also note that only 1000 views are allowed on the documentation per month. It is the same for all the plans in Postman. After your 1000 views are completed, your documentation will not be accessible until 30 days are completed. Starting with this, let us publish documentation in Postman.

Open your Postman application ( Make sure you are signed out ).

Import the collection from here . (Refer How to import collections in Postman ).

Once you have imported your collection, you will see it in the sidebar.



This will open up a new panel.

Select the edit icon on the description to edit the description.






This option can be used to view the documentation temporarily as it would like after publishing. Coming back to Publish Docs Option. Press the Publish Docs option as discussed in point 8.

This option will open up a web page in your browser to select your environment name.


Note : You can refer to the Environment and Variables in Postman tutorial to know more about the environment.


You can also click on the Show Custom Styling Options to change the colour scheme of the documentation.

Click on Publish Collection to publish the collection.


Note : Let all users discover this collection in the Postman app is used for letting your collection available to the Postman family. For this, your API should be one which is not specific to you but can be used by anyone learning or expert. It should have a defined workflow since it will be seen by the Postman community publicly.

16.  You will see this web page that your collection is published .


You can edit or unpublish your collection from this screen. You will get a published public URL for your documentation.

API Documentation in Postman

What gets automatically generated?

Since you own written API Documentation can have any number of fields, only a few and important fields are created when we create the documentation using Postman. So your documentation will include:


Descriptions associated with requests, folders, and collections. This will also contain the method type, headers and body code ( if any ).




Postman uses ordered requests and folders to organize documentation in sections to reflect the structure of your collection. You can customize descriptions using  Markdown  styling with embedded graphics to complement your documentation. Postman supports GitHub-flavored Markdown so you can include tables. When including block elements, make sure you leave an empty line before and after to avoid any rendering issues.

You can now share this documentation to whomsoever you want to use your API. You can find more options here and there to edit the documentation in one way or other. Involve yourself in this for some time to extract every detail about the documentation and it will definitely help you in the future. As I discussed above, an API is useful as long as it's documentation is crisp and understandable.

GUID in Postman

Similar Articles

Postman Tutorial


Supported by

Trump Was Taped Discussing Sensitive Document He Had Kept After Leaving Office

Federal prosecutors obtained the recording as part of their investigation into the former president’s handling of classified documents.

Former President Donald Trump in a blue suit with a red tie and an American flag lapel pin, with blue curtains in the background

By Maggie Haberman ,  Jonathan Swan and Alan Feuer

Federal prosecutors investigating former President Donald J. Trump’s handling of classified material have a recording of Mr. Trump from 2021 discussing a sensitive military document he had kept after leaving the White House, two people briefed on the matter said.

In the recording, Mr. Trump suggested he knew the document was secret and had not declassified it, one person briefed on the matter said.

The existence of the recording could undermine Mr. Trump’s repeated claim that he had already declassified material that remained in his possession after he left office. Prosecutors are scrutinizing whether Mr. Trump obstructed efforts by federal officials to retrieve documents he took with him after leaving office and whether he violated laws governing the handling of classified material.

The existence of the recording was reported earlier by CNN.

The recording was made during a meeting Mr. Trump held in July 2021 with people helping his former chief of staff, Mark Meadows, write a memoir of his 10 months in the White House, according to the people briefed on the matter. The meeting was held at Mr. Trump’s club at Bedminster, N.J., where he spends summers.

Until now, the focus of the documents investigation has been largely on material Mr. Trump kept with him at Mar-a-Lago, his private club and residence in Florida, rather than in New Jersey.

Mr. Meadows did not attend the meeting, but at least two of Mr. Trump’s aides did. One, Margo Martin, routinely taped the interviews he gave for books being written about him that year.

On the recording, Mr. Trump began railing about his handpicked chairman of the Joint Chiefs of Staff, Gen. Mark A. Milley, who was described in media accounts at the time as having guarded against Mr. Trump’s striking Iran in the final days of the presidency, according to the people briefed on the matter.

Mr. Trump then began referencing a document that he had with him, saying that it had been compiled by General Milley and was related to attacking Iran, the people briefed on the matter said. Among other comments, he mentioned his classification abilities during the discussion, one person briefed on the matter said. Mr. Trump can be heard handling paper on the tape, though it is not clear whether it was the document in question.

The Justice Department obtained the recording in recent months, a potentially key piece in a mountain of evidence that prosecutors have amassed under the special counsel, Jack Smith, since he was appointed in November to oversee the federal investigations into Mr. Trump.

Ms. Martin was asked about the recording during a grand jury appearance, according to two of the people briefed on the matter.

In an interview with CNN on Wednesday night, James Trusty, a lawyer representing Mr. Trump in the case, indicated that the former president was taking the position that he had declassified the material he took with him upon leaving office.

“When he left for Mar-a-Lago with boxes of documents that other people packed for him that he brought, he was the commander in chief,” Mr. Trusty said. “There is no doubt that he has the constitutional authority as commander in chief to declassify.”

Mr. Trusty said officials could prove that Mr. Trump had declassified material. But when pressed on whether Mr. Trump had declassified the document in question at the Bedminster meeting, Mr. Trusty declined to say.

In total, the government has recovered more than 300 documents with classified markings from Mr. Trump since he left office. They include a first batch of documents returned in January of last year to the National Archives, another set provided by Mr. Trump’s aides to the Justice Department that June, material seized by the F.B.I. in the search of Mar-a-Lago in August and a handful found in additional searches late last year.

One set of documents found by the F.B.I. during the search had the highest level of classification, top secret/sensitive compartmented information.

Mr. Trump has long touted what he claimed was his ability to automatically declassify materials and has even said he could do so with his mind.

His allies have insisted he had a standing order to declassify material when he took it from the Oval Office to the White House residence, a claim that several former senior administration officials have suggested is nonsense. Members of his legal team have cautioned his aides not to lean too heavily on that argument as a defense in the documents case.

That claim was raised most vocally by Kash Patel, a close adviser to Mr. Trump who testified to a grand jury under an immunity deal forced on him by prosecutors.

The recording obtained by the special counsel’s office could help prosecutors undercut any argument by Mr. Trump that the documents he had taken from the White House upon leaving office were declassified. It could also assist them in making a case that Mr. Trump was aware that his abilities to possess — and to show off — classified materials were limited.

Moreover, one of the laws cited by the Justice Department in seeking the warrant used to search Mar-a-Lago last year, known as the Espionage Act, was enacted by Congress during World War I, decades before President Harry S. Truman issued an executive order creating the modern classification system for the executive branch.

As a result, the Espionage Act makes no reference to whether a document has been deemed classified. Instead, it makes it a crime to retain, without authorization, documents related to the national defense that could be used to harm the United States or aid a foreign adversary.

Investigators have been asking witnesses about General Milley in various interviews for several weeks, although they have generally left unclear what they were looking for.

Investigators have several if not all of the recordings of book interviews that Mr. Trump gave, according to two of the people familiar with the events.

In one interview, Mr. Trump said he had taken “nothing of great urgency” when asked if he had anything in his possession.

Mr. Trump has equivocated when asked if he ever showed any classified documents to people once he left the White House. At a CNN town hall event in May, he said, “Not really. I would have the right to. By the way, they were declassified after.”

Mr. Meadows, in his book, appeared to echo Mr. Trump’s claim about General Milley.

“The president recalls a four-page report typed up by Mark Milley himself,” the book said. “It contained the general’s own plan to attack Iran, deploying massive numbers of troops, something he urged President Trump to do more than once during his presidency. President Trump denied those requests every time.”

Yet according to a person familiar with the document in question, the report was not written by General Milley and appears to date to an earlier period in the Trump administration, when Gen. Joseph F. Dunford Jr. was the chairman of the Joint Chiefs of Staff and Jim Mattis was the defense secretary.

General Milley has been interviewed by investigators about the matter, according to one person briefed on the discussion.

Maggie Haberman is a senior political correspondent and the author of “Confidence Man: The Making of Donald Trump and the Breaking of America.” She was part of a team that won a Pulitzer Prize in 2018 for reporting on President Trump’s advisers and their connections to Russia. @ maggieNYT

Jonathan Swan is a political reporter who focuses on campaigns and Congress. As a reporter for Axios, he won an Emmy Award for his 2020 interview of then-President Donald J. Trump, and the White House Correspondents’ Association’s Aldo Beckman Award for “overall excellence in White House coverage” in 2022. @ jonathanvswan

Alan Feuer covers extremism and political violence. He joined The Times in 1999. @ alanfeuer


  1. Documenting and testing APIs with Postman

    how to write postman documentation

  2. How To Create API Documentation In Postman?

    how to write postman documentation

  3. 查看文档_PostMan中文文档

    how to write postman documentation

  4. Public API documentation

    how to write postman documentation

  5. Navigating Postman

    how to write postman documentation

  6. postman-docs/ at develop · postmanlabs/postman

    how to write postman documentation


  1. Write a comment and I'll give you (terrible) advice #shortsviral #advice

  2. Debugging Collection Runs

  3. API test automation with POSTMAN

  4. Nestjs backend rest api

  5. 02

  6. Customize Public Documentation


  1. API Documentation: How to Write, Examples & Best Practices

    Four of the most common types are: Reference documentation: Reference documentation typically provides a rundown of every endpoint, including its methods, parameters, and accepted data types. This type of documentation also describes—in plain language—what each endpoint is intended to do.

  2. API Documentation Tool

    Postman allows you to publish documentation quickly and easily. Postman automatically pulls your sample requests, headers, code snippets, etc. to populate your documentation page with dynamic examples and machine-readable instructions so you can easily share your API with the rest of the world.

  3. Generating API documentation

    The Postman blog is your hub for API resources, news, and community. Learn about the Postman API Platform and much more. No search results found; Home / Generating API documentation. Last modified: 2023/06/05 ← .

  4. Building requests

    Home / Sending requests Building requests You can send requests in Postman to connect to APIs you are working with. Your requests can retrieve, add, delete, and update data. Whether you are building or testing your own API, or integrating with a third-party API, you can send your requests in Postman.

  5. How To Create API Documentation In Postman?

    Follow the below steps for adding basic info about the requests and then creating the documentation. #1) Create a collection with 3 requests i.e. Register User, Login User and Get User (Refer here for request payloads and API URLs). #2) Now let's add some info in markdown format to the collection.

  6. How to Get Started with the Postman API

    Open the " User " folder by clicking on it. Click on " GET API Key Owner .". You should see a screen similar to the one below. If you click on " Send " now (the big blue button), you will get an HTTP 401 (Unauthorized) response, as expected.

  7. The Good Documentation Checklist

    1. Create a Postman Collection Generate from an API specification: If you're using an API specification format, such as OpenAPI, you can import a spec file into Postman to automatically generate a collection. Once you have a collection, you can automatically generate web-viewable Postman documentation.

  8. api

    See the documentation in the README if you want additionnal information. From there you will find recommandations for taking full advandage of the tool, or change the look of your documentation by using custom themes. The Github presentation also provides a reference to a generated example documentation.

  9. How to create and publish API documentation with Postman?

    Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs faster. To get the latest version of the Postman desktop app, visit the download page and select Download for your platform. See the Postman installation and updates page for more information. Steps to create API documentation using ...

  10. How to Document APIs With Postman

    Programming How to Document APIs With Postman By Ukeje Chukwuemeriwo Goodness (Goodnessuc) Published Mar 31, 2023 An API is only as good as its documentation, so make sure yours are easy to understand and use with Postman's support. Readers like you help support MUO.

  11. How to Generate API Documentation in Postman?

    Open your Postman application ( Make sure you are signed out ). Import the collection from here. (Refer How to import collections in Postman ). Once you have imported your collection, you will see it in the sidebar. Now, select the small arrow that appears beside the collection name when you hover the mouse over it.

  12. How to create API documentation in Postman [under 5 Minutes] 2023

    Learn How to create API documentation in Postman under 5 Minutes! Please consider supporting this channel by subscribing.Watch How to run API in Postman [in ...

  13. Postman: How to Write Files to Disk?

    Write the script below inside a file called writeToDisk.js. Open a terminal in the folder where you have saved the script and run the following command: node writeToDisk.js. Great, so now we know ...

  14. Postman API Platform

    Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. ... documentation, and mocking to discovery. API Repository. Easily store, iterate and collaborate around all your API artifacts on one central platform used across teams ...

  15. Trump Was Taped Discussing Sensitive Document He Had After Leaving

    The recording was made during a meeting Mr. Trump held in July 2021 with people helping his former chief of staff, Mark Meadows, write a memoir of his 10 months in the White House, according to ...