Using postman to create an api documentation.

If you are a backend developer, then you must have used postman to test your APIs. It can be really handy for testing APIs. You have tested the API, it’s working and now your frontend team needs the API and the ways to use it. You have to document the API including details about all the routes and data they give with authentication methods as well. It will be pretty troublesome to start writing everything about the things that you have already done, right? Here comes the postman in your rescue. It allows users to create documentation without you having to make requests to routes again and copying the examples to let them know about the response format. So, in this article let’s discuss the easy and automatic way to generate the API documentation with examples for each route. For this, I have a simple Nodejs application that serves the user data when we visit the /users route.

const express = require('express')
const app = express()

const users = [
    {
        id: 1,
        name: 'John Doe'
    },
    {
        id: 1,
        name: 'Jane Doe'
    },
    {
        id: 1,
        name: 'Mary Doe'
    },
]
app.get('/users',(req,res) => {
    res.json(users)
})

app.listen(4000, ()=> {
    console.log('server started')
})

Now, let’s start the server with command node index.js and open postman desktop application. Once you open it, in your left tab you can create a new collection clicking on the New option and can rename anything you like. I am naming it as an example.

create a collection

add request Great, you have a collection now. Now, let’s add a request in the collection. For this, you can simply click on Add a request option as shown in the image above. In our case, we have a get request to fetch the user. I have named the request to get users for understanding.

request the api in postman Once you click on Send button you will get the users as shown in the image. response example postman Cool, our API is working. Let’s save the response, so that it can be used as an example in the documentation. And don’t forget to save the request as well by clicking on the save icon just above the Send button. Now let’s document our API. Click on the three dots next to your collection and click on view documentation.

document the api.png There you go, you have successfully generated documentation for your api. Another cool thing postman allows you to do is publish your documentation and share it with your team. Let’s do that. On the right hand side you can see publish option. Click there and your job is almost done.

You will be taken to your browser where you can customize the looks of your documentation along with background and highlight colors. When you scroll a bit you can see a publish collection button. Press the button to publish the documentation. You will be provided with a link to your documentation page.

Hurray! You have published your first api documentation without any hassles.

Conclusion

You can also add an introduction to your api, and other details in the postman. Just play around and you will find it really easy to do everything you want while documenting your api. Hope you find it useful.

Documenting your API using postman

Conclusion