Oftentimes, beginners have asked the question, How can I publish an API on Postman?
Today, I will be writing about a quick guide to help you through this process. But, first, I would like to talk a little about Postman.
Postman is an application for testing and documenting your API endpoints.
In Postman, you can group your requests or endpoints into something called a COLLECTION to help keep your workspace organized, collaborate with teammates, generate API documentation, and automate request runs (i.e you don't have to always write requests each time you want to run them or return a response).
As a backend developer, when you create an API or an endpoint, you most likely won't be the one to consume or use it. Your endpoint(s) is most likely to be used by other developers thus there is a need to create documentation for the endpoints you have created. After creating a collection and testing that your endpoints work, you then have to PUBLISH that collection. This makes the collection accessible to other people via a URL. This URL holds your written documentation. It usually starts with "documenter.postman..."
Now, let's proceed to why we are here. But, before you dive right in, I am assuming you already have basic knowledge of creating an API - making a request and receiving a response. If yes, then below are the steps to take to create and publish your own API documentation on Postman
1. Create a Collection
Click on the Collections tab
Click the + New Collection
Enter the "Name" of the collection
Add a "Description". Note, that this is optional
Click the Create button
- You should be able to see the Users collection as part of the list of collections you have.
2. Create an Endpoint and Save it into a Collection.
- Create an endpoint. E.g. localhost:8080/api/test-users
Click on the Save dropdown button
Click on Save as
- You can rename the endpoint if you want to. E.g. Get Users
Scroll down, select the collection you want to save the endpoint into
Click on the Save button
- You should be able to see the saved endpoint inside the collection
Let's save the Response we got after making the GET request
Click on the Save Response dropdown
Click on Save as example
- Finally, click on the Save Example button
- Repeat step 2 for all other requests or endpoints
3. Publish the Collection
Hover on the collection you created (e.g. Users), and click on the three-dotted icon on the right-hand side of it.
Click on Publish Docs. A page will open on the web browser.
You can choose to change the default colors provided by the postman
Scroll down to the bottom of the page
Click on the Publish Collection button
- You will be redirected to a page where you can see the URL generated for the API documentation
- Here is the URL generated for me