Discussing Two API Documentation Tools: Postman and Swagger

The Issue

As a programmer, writing code is a given. Beyond spending hours typing out logic, there are many other tasks we need to accomplish. Among them, adding documentation for what we write is nearly inseparable.

While still in school, Software Architecture was an essential subject for students majoring in application software programming. We learned many models, diagrams, and even processes for developing applications. These concepts are occasionally referenced in the workplace, such as waterfall, agile scrum… or diagrams for activities, sequences… of a particular function.

To be honest, there was a time when I really hated the task of writing documentation; I even thought it was a waste of unnecessary time. Instead of drawing diagrams and writing documentation, I believed that the superior logic conceived while coding was much more worthy of my time.

Since graduating, building an API system has almost been a continuous task. I can create hundreds of CRUD operations with parameters ranging from simple to complex, "spreading" them to my colleagues by sending direct messages, or sometimes "noting" them in a memo. More "professionally," I would send a link to Postman, where the templates of the created APIs are stored. But no matter the method, it was merely a temporary solution for conveying information.

What goes around comes around, and the consequences soon followed as I occasionally found myself inundated with questions about input data and the meaning of each data field I created. Oh dear! Did I create this feature or not? Why does everything seem so unfamiliar? Why is this required, and what is the purpose of that?

That's a joke, but the situation isn't as serious as you might think 😅. Over time, we all have to grow up; interacting with and learning from those who came before me has allowed me to gain more knowledge. Oh, it turns out there's a standard for creating documentation for API systems, commonly encountered as Postman Collections and Swagger.

Postman

Postman likely needs little introduction. It's a classic software that I believe most programmers are familiar with. I heard it started as software for testing APIs. Over time, it gradually evolved into an API platform for developers to design, build, test, and collaborate on APIs. In short, it's an API client.

A fundamental concept of Postman is Collections. A set of endpoints forms a Collection. Typically, developers add endpoints to Collections and save them for later use or share them with each other. Interestingly, from Collections, you can publish a complete API documentation page.

Take a look at an example of Cloudflare's API at Cloudflare Client API v4; you can see a complete list of endpoints along with the necessary parameters in the body and headers. It looks much more professional than the previous method of writing notes.

Creating API documentation using Collections is quite simple. After creating a Collection and adding endpoints, right-click the name, select "View documentation," and you'll see a preview of the documentation page. If you want to publish the content on the Internet, click "Publish" in the upper right corner, a web window will open with settings before you are ready to publish. Finally, click Publish to complete.

You can also add descriptions to each endpoint for additional detail. In each endpoint addition screen, click the "Documentation" box and enter the description; this information will also appear on the published documentation page.

Overall, writing documentation using Postman Collections is relatively easy and quick. However, there are some limitations, such as not clearly displaying parameter types, indicating which parameters are optional or required, and handling more complex requirements like generating documentation automatically from code… At times like these, we need another name - Swagger.

Swagger

Swagger is an open-source toolset used to design, build, document, and utilize as a client to access RESTful web services. Swagger helps API developers accurately and consistently describe their services.

OpenAPI is a technical specification for RESTful APIs, developed from the Swagger project. OpenAPI allows developers to describe their entire API in a single document (usually in YAML or JSON format).

Here's an example of an API documentation page created from a YAML file Swagger Petstore. It features a clearly categorized list along with detailed information for each endpoint. Swagger also acts as an API client, allowing you to test API endpoints directly on the website.

Swagger includes various tools to help create OpenAPI structures, such as Swagger UI, Swagger Editor, Swagger Codegen… Among these, UI and Editor serve as interfaces and editors, while Codegen is an automatic code generation tool supporting over 40 programming languages.

Being a powerful tool, getting started with Swagger can be quite complex. It requires time to research and learn to apply it in the documentation creation process. There is a dedicated documentation page that thoroughly guides you through using Swagger Editor to create OpenAPI structures at OpenAPI Guide.

A quicker approach is to refer to the example documentation page mentioned above. Study its YAML file to learn how to copy and add a new endpoint immediately. Remember that most of the necessary components for creating documentation are available in Swagger, so utilize your search skills to know how to incorporate them into your project.

Overall, all you need is a YAML structure containing the OpenAPI specification, then input this content into Swagger UI; it will display the content similarly to the example mentioned earlier in the article.

Next, try to start researching how to generate documentation automatically through coding. You know nestjs, right? Check out how they guide automatic documentation generation at OpenAPI Introduction. Besides Nest, there are many libraries/frameworks that also support creating this OpenAPI structure.

Conversion

Due to the popularity and usefulness of Postman and Swagger, there are ways to convert between these two formats. That is, from Collections to OpenAPI and vice versa, depending on personal preference.

postman-to-openapi is an example of a tool that converts Collections to OpenAPI. Conversely, Postman has built-in support for importing structured YAML files of OpenAPI to create Collections Postman Supports OpenAPI 3.0. So, you just need to go to Postman, select "Import," and upload the YAML file of OpenAPI to complete the process.

Conclusion

Above is a brief introduction to two tools that assist in creating API documentation, ranging from simple to complex. Depending on the situation and needs, one can choose the most appropriate method. While Postman is very simple to start with, Swagger requires a bit more time to learn how to use.

What tools or methods are you using to document APIs? Please share in the comments below. Thank you!