This post is also available in: Español (Spanish)
After you or your organization have spent months developing your services, the time comes when you have to document your API.
Instead of writing the documentation by hand and taking weeks to make it readable, we have a multitude of tools that simplify this task.
I will explain how to generate your technical API documentation in less than 15 minutes.
There are several ways to document an API. Swagger deserves an honorable mention. Swagger is a series of OpenSource tools that allow you to create your API documentation from comments in your code or from a defined schema. I highly recommend this tool if you have not yet created your service and are creating the schema for it. But in our case, we already have the service running and for this purpose, Postman is better.
Creating documentation with Postman will allow us to have a public or private link to our service’s API documentation and provide version control, modify documentation collaboratively and much more. All this for free and agnostic of the language in which you have developed.
Kicking off
To create our documentation with Postman, of course, we will need Postman. So if you don’t have it: download it.
What is Postman?
It is a client for making REST, SOAP and GraphQL requests. With features such as automatic testing of your services, monitoring the status of your API, working collaboratively on the development of your API mockup and much more.
Learn more about Postman here: Initial Postman Guide.
The process for creating the documentation is simple. Basically, we have to have the collection of API calls that we want to collect in the documentation. And add the relevant descriptions to each call and parameter.
So here we go!
Note: If you already have a collection with your calls you can skip these steps and go directly to the Document section.
Create a colection in Postman.
A collection is a folder that stores the set of requests related to an API.
To create the new collection we click on “New Collection” in the left column of the Postman panel. We then add the name and description of the API. This information will be added to your API documentation.
Add a request
Once our collection is created, we have toadd the different requests we want to include in the API documentation. The nice thing about Postman, is that since it’s an API Rest test client, we can use it to test that our requests work, before they are added to the documentation.
To add a new request to our newly created collection, click on “Add request” or make a new tab in the request view.
Here we have to add the request data to our API calls, and we will have to do this for each of the API calls that we want to include in the documentation.
We will test our request and may save the answer as a sample response to be used in the documentation. With a successful request, we will also ensure that the Headers and HTTP verbs (GET, POST, PUT, …) work and are added correctly to the documentation.
Documenting
To structure the documentation, we can create folders within the collections, in order to better organize the requests by category.
It is also worth adding descriptions to the requests and parameters, so that your documentation is complete.
You can add this when saving the request to the collection, remember to select the collection you just created.
With this we already have a Collection that contains requests to our API and if we have run them, we already have the example answers. If we have added the descriptions to our parameters and to our Requests, we would already have all the information ready for the documentation. – And that’s how it’s done, the final result is just a few clicks away.
Generating documentation
To generate the documentation and to be able to sow the wonderful fruits of our work, we only have to go to the options of the collection and click on “Publish Docs”.
A window will open in your browser, allowing you to configure the details of your documentation. You don’t have to modify anything to make it work, but it can be adapted to your needs. Finally, click on the big “Publish” button in that browser window and you will have the public link to your just created documentation.
Mr¡ore things
We now have the documentation for our API. As we update our requests in Postman and save them, we can republish to update the changes.
You can also invite editors, so they can download the collection of requests, test them and modify them.
With this we now have our API documentation.
Free, hosted, simple and in less than 15 minutes!