This blog teaches you how to document your Postman collections using Markdown and comments. You will learn how to use Markdown syntax and features to format your documentation and how to use comments to add notes and feedback to your requests and responses.
1. Introduction
Postman is a popular tool for testing and developing APIs. It allows you to create, organize, and execute requests, as well as share and collaborate on collections with your team. But how do you document your Postman collections and requests? How do you add descriptions and explanations to your API endpoints, parameters, headers, and responses? How do you make your collections more readable and understandable for yourself and others?
In this tutorial, you will learn how to document your Postman collections using Markdown and comments. You will learn how to use Markdown in Postman to format your documentation with headings, lists, tables, images, links, and more. You will also learn how to use Postman comments to add notes and feedback to your requests and responses. By the end of this tutorial, you will be able to create well-documented and user-friendly collections that can help you and your team work more efficiently and effectively with APIs.
Ready to get started? Let’s begin by learning how to use Markdown in Postman.
2. How to use Markdown in Postman
Markdown is a lightweight markup language that allows you to format text using simple syntax. You can use Markdown to add headings, lists, tables, images, links, and more to your text. Markdown is widely used for writing documentation, README files, blog posts, and other online content.
Postman supports Markdown in various places, such as collection descriptions, request descriptions, folder descriptions, and response examples. You can use Markdown to document your Postman collections and make them more informative and user-friendly. For example, you can use Markdown to add a title, a summary, and a table of contents to your collection description. You can also use Markdown to add explanations, examples, and references to your request descriptions.
But how do you use Markdown in Postman? What are the syntax and features of Markdown? How do you preview and edit your Markdown text in Postman? In this section, you will learn the answers to these questions and more. You will learn how to use Markdown syntax and Markdown features to format your documentation in Postman.
2.1. Markdown syntax
Markdown syntax is the set of rules that define how to format text using Markdown. Markdown syntax consists of symbols and characters that you can use to create different elements, such as headings, lists, tables, images, links, and more. For example, you can use the hash sign (#) to create a heading, the asterisk (*) to create a bullet point, and the square brackets ([]) and parentheses (()) to create a link.
To use Markdown syntax in Postman, you need to enter your text in the description or example fields of your collection, folder, or request. You can use the toggle switch at the bottom of the field to switch between the edit and preview modes. The edit mode allows you to enter and edit your Markdown text, while the preview mode allows you to see how your text will look like when formatted with Markdown.
Here are some examples of how to use Markdown syntax in Postman:
- To create a heading, use one or more hash signs (#) followed by a space and your heading text. The number of hash signs determines the level of the heading. For example,
# Heading 1creates a level 1 heading, while## Heading 2creates a level 2 heading. - To create a list, use a hyphen (-), an asterisk (*), or a plus sign (+) followed by a space and your list item. To create a nested list, indent your list item with four spaces or a tab. For example,
- Item 1creates a list with two items and two subitems.
- Subitem 1
- Subitem 2
- Item 2 - To create a table, use pipes (|) to separate the columns and dashes (-) to separate the header row from the body rows. You can also use colons (:) to align the columns. For example,
| Name | Age | Gender |creates a table with three columns and two rows.
| --- | --- | --- |
| Alice | 25 | F |
| Bob | 30 | M | - To create an image, use an exclamation mark (!) followed by square brackets ([]) containing the image alt text and parentheses (()) containing the image URL. You can also add an optional title attribute inside the parentheses after the URL. For example,
![Postman logo](https://postman.com/images/logo.png "Postman logo
2.2. Markdown features
Markdown features are the different elements that you can create using Markdown syntax. Markdown features include headings, lists, tables, images, links, and more. You can use Markdown features to enhance your documentation and make it more attractive and interactive. For example, you can use images to illustrate your API responses, links to provide references and resources, and tables to display data and information.
In this section, you will learn how to use some of the most common and useful Markdown features in Postman. You will learn how to create and format images, links, tables, code blocks, and inline code. You will also learn how to use some of the advanced Markdown features, such as HTML tags, emojis, and math expressions. By the end of this section, you will be able to use Markdown features to create rich and engaging documentation for your Postman collections.
Let’s start by learning how to create and format images using Markdown in Postman.
3. How to use comments in Postman
Comments are another way to document your Postman collections and add notes and feedback to your requests and responses. Comments are short messages that you can attach to any request or response in Postman. You can use comments to explain your logic, share your thoughts, ask questions, or provide suggestions. Comments are visible to anyone who has access to your collection, and you can also reply to other people’s comments.
To use comments in Postman, you need to enable the comment mode by clicking on the comment icon at the top right corner of the Postman app. The comment mode allows you to view and add comments to any request or response in your collection. You can also use the comment mode to filter, sort, and search for comments.
Here are some examples of how to use comments in Postman:
- To add a comment to a request, select the request from the sidebar and click on the comment icon at the bottom right corner of the request builder. A comment box will appear where you can enter your comment and click on the send icon to post it.
- To add a comment to a response, select the request from the sidebar and send it. Then, click on the comment icon at the bottom right corner of the response viewer. A comment box will appear where you can enter your comment and click on the send icon to post it.
- To reply to a comment, hover over the comment and click on the reply icon. A reply box will appear where you can enter your reply and click on the send icon to post it.
- To edit or delete a comment, hover over the comment and click on the three dots icon. A menu will appear where you can choose to edit or delete the comment.
Comments are a great way to communicate and collaborate with your team and make your collections more understandable and useful. In the next section, you will learn how to add comments to requests and responses using some examples.
3.1. Adding comments to requests
Adding comments to requests is a useful way to document your Postman collections and provide notes and feedback to yourself and your team. You can use comments to explain the purpose, logic, and parameters of your requests, as well as to share your thoughts, questions, and suggestions. Comments can help you and your team understand and improve your requests and make your collections more maintainable and collaborative.
To add a comment to a request, you need to follow these steps:
- Select the request from the sidebar and click on the comment icon at the bottom right corner of the request builder.
- A comment box will appear where you can enter your comment. You can use Markdown syntax to format your comment, such as adding headings, lists, tables, images, links, and more.
- Click on the send icon to post your comment. Your comment will appear below the request builder, and you can also view it in the comment mode.
Here is an example of how to add a comment to a request using Markdown syntax:
# GET request to fetch a user by ID - This request uses the `users` endpoint of the JSONPlaceholder API - The `id` parameter is set to 1 to fetch the user with the ID of 1 - The response should return a JSON object with the user's details - You can change the `id` parameter to fetch other users - Do you think we should add more parameters to this request? Let me know in the comments.
As you can see, adding comments to requests can help you document your Postman collections and make them more readable and understandable. In the next section, you will learn how to add comments to responses using some examples.
3.2. Adding comments to responses
Adding comments to responses is another useful way to document your Postman collections and provide notes and feedback to yourself and your team. You can use comments to explain the status, headers, and body of your responses, as well as to share your thoughts, questions, and suggestions. Comments can help you and your team understand and improve your responses and make your collections more maintainable and collaborative.
To add a comment to a response, you need to follow these steps:
- Select the request from the sidebar and send it. You will see the response in the response viewer.
- Click on the comment icon at the bottom right corner of the response viewer. A comment box will appear where you can enter your comment. You can use Markdown syntax to format your comment, such as adding headings, lists, tables, images, links, and more.
- Click on the send icon to post your comment. Your comment will appear below the response viewer, and you can also view it in the comment mode.
Here is an example of how to add a comment to a response using Markdown syntax:
# Response for the GET request to fetch a user by ID - The response status is 200 OK, which means the request was successful - The response headers include the content-type, date, and connection information - The response body is a JSON object with the user's details, such as name, username, email, address, phone, website, and company - The response matches the expected output for this request - Do you have any questions or feedback about this response? Let me know in the comments.
As you can see, adding comments to responses can help you document your Postman collections and make them more readable and understandable. In the next section, you will learn how to conclude your tutorial and provide some useful resources and tips.
4. Conclusion
In this tutorial, you have learned how to document your Postman collections using Markdown and comments. You have learned how to use Markdown syntax and features to format your documentation with headings, lists, tables, images, links, and more. You have also learned how to use Postman comments to add notes and feedback to your requests and responses. By following this tutorial, you have created well-documented and user-friendly collections that can help you and your team work more efficiently and effectively with APIs.
Here are some key points to remember from this tutorial:
- Postman supports Markdown in various places, such as collection descriptions, request descriptions, folder descriptions, and response examples.
- Markdown syntax is the set of rules that define how to format text using Markdown. Markdown syntax consists of symbols and characters that you can use to create different elements, such as headings, lists, tables, images, links, and more.
- Markdown features are the different elements that you can create using Markdown syntax. Markdown features include headings, lists, tables, images, links, and more. You can use Markdown features to enhance your documentation and make it more attractive and interactive.
- Comments are short messages that you can attach to any request or response in Postman. You can use comments to explain your logic, share your thoughts, ask questions, or provide suggestions. Comments are visible to anyone who has access to your collection, and you can also reply to other people’s comments.
- You can use the toggle switch at the bottom of the description or example fields to switch between the edit and preview modes. The edit mode allows you to enter and edit your Markdown text or comments, while the preview mode allows you to see how your text will look like when formatted with Markdown or comments.
- You can use the comment icon at the top right corner of the Postman app to enable the comment mode. The comment mode allows you to view and add comments to any request or response in your collection. You can also use the comment mode to filter, sort, and search for comments.
We hope you enjoyed this tutorial and found it useful. If you have any questions or feedback, please let us know in the comments below. You can also check out the following resources to learn more about Postman, Markdown, and comments:
- Postman Learning Center: The official documentation and learning platform for Postman.
- Markdown Guide: A comprehensive and easy-to-follow guide to Markdown.
- Commenting on collections: A detailed guide on how to use comments in Postman.
Thank you for reading this tutorial and happy documenting!
