NODE-Express REST API Documentation with POSTMAN, APIMATIC, and Swagger-UI-Express

You probably have gotten to that point where you need to write or publish the documentation for your API and then you get to know about Swagger being the most popular tool for such a thing. You research about swagger and plan to do the documentation as fast as possible but then working with swagger seems so confusing you don’t know where to start from or how to go about what you think should be a trivial task.

To think about having to type the docs manually on the Swagger editor dreads you so much and then you think you should skip this documentation till later or use another tool.

Swagger has a great set of tools for making a quality API documentation, but its ubiquity in the documentation ecosystem makes it confusing for most beginners.

Enough of the Swagger analysis, I will list this down in steps to make the tutorial easy to follow, as the process should be as simple as possible.

STEP I: Generating the Documentation With POSTMAN

Intro to API documentation
_Select if you want to create documentation for a new API or an existing or team collection. If you create a new API to…_www.getpostman.com

API documentation through Postman is as easy as creating a collection, running requests for each of your implemented routes, saving each request to the collection including the sample responses (failure and success responses to make your documentation rich), and exporting the collection.

If that seemed much, read through again and just follow the steps as stated, we won’t be talking much about API documentation through Postman as it seems like almost a trivial task and to keep this tutorial as lean as possible, a whole lot of other tutorials out there explain better how to do it.

What is actually needed from this step is a JSON(Postman docs) file which gets exported through the created collection menu.

Exporting A POSTMAN Collection

STEP II: Converting the Generated POSTMAN Docs to a Swagger or OpenAPI Specification

I discovered a simple platform, apimatic.io to do this through a search. The platform requires that you’d register to use their API transformer service to convert the JSON file to our desired output (p̶r̶e̶f̶e̶r̶a̶b̶l̶y̶ ̶O̶p̶e̶n̶ ̶A̶P̶I̶ ̶v̶3̶.̶0̶).

You might want to leave the default output (Open API/Swagger v2.0) the converter gives (the previously suggested Open API v3.0 seems to be difficult to try out the requests with).

STEP III: Serving the Converted file through our App

This step requires the installation of swagger-ui-express, a pretty straightforward package that does the actual job of serving the API documentation. The major highlight from the package docs is as below:

STEP IV: View the Documentation in the Browser

This is not necessarily a step, but then, you would want to see what the docs looks like in your browser depending on the path specified in step III — e.g. localhost:3000/api-docs

Sample API Documentation Generated Through Postman and Converted With Apimatic

A Few Things to Note

1. The documentation from Postman should be as rich as possible as it determines the served API documentation at the end. There should be enough sample responses from a single route.
2. Agreed, this is the lazy approach to generating an API documentation (not totally lazy since there is a lot to do with Postman). The documentation might not be as rich creating the docs through the swagger editor. It is strongly advised to edit the converted file on the Swagger editor.
3. A disclaimer actually; I discovered Apimatic through a Google search, I am not in anyway affiliated with the owners or getting paid to talk about the platform.

I would like to know your thoughts about this post and the quality of the documentation you get to generate with it in the comments.

Thank you.